Editable

"use client";

import {
  Editable,
  EditableArea,
  EditableControl,
  EditableEditTrigger,
  EditableInput,
  EditablePreview,
} from "@/siteplane/components/editable";
import { Field, FieldLabel } from "@/siteplane/components/field";

export default function Example() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel>Project name</FieldLabel>
      <Editable
        defaultValue="Spring campaign"
        labels={{ edit: "Rename project" }}
        placeholder="Add a project name"
      >
        <EditableArea>
          <EditablePreview />
          <EditableInput />
        </EditableArea>
        <EditableControl>
          <EditableEditTrigger />
        </EditableControl>
      </Editable>
    </Field>
  );
}

Installation

pnpm dlx shadcn@4.18.0 add @siteplane/editable

For this page’s examples, also install:

pnpm dlx shadcn@4.18.0 add @siteplane/card

Field is installed with Input, which Editable installs.

Usage

import {
  Editable,
  EditableArea,
  EditableControl,
  EditableEditTrigger,
  EditableInput,
  EditablePreview,
} from "@/siteplane/components/editable";

<Editable defaultValue="Spring campaign" labels={{ edit: "Rename project" }}>
  <EditableArea>
    <EditablePreview />
    <EditableInput aria-label="Project name" />
  </EditableArea>
  <EditableControl>
    <EditableEditTrigger />
  </EditableControl>
</Editable>;

Composition

Editable
├── EditableArea
│   ├── EditablePreview
│   └── EditableInput or EditableTextarea
└── EditableControl
    └── EditableEditTrigger

At rest, EditablePreview shows the value and EditableEditTrigger shows a pencil beside it. The pencil opens the field in the same place, filled with the value and with its text selected. Enter, or a click or a focus move outside the editable, keeps the change and calls onValueCommit. Escape puts back the value from when editing started and calls onValueRevert. Focus then returns to the pencil. The field stays in the document while it is hidden, so its name submits with a form.

The text never moves: the value stands where the field's text stands, and only the field's frame fades in around it when the field opens and out when it closes. At rest the row is as tall as the field and the value starts where the field's text starts, so the frame stands where every field stands, flush with its label and 8 px under it. Focus moves into the field at once, so typing right after the pencil loses no keystroke. With reduced motion, the frame appears and goes at once.

Label the value with a Field and FieldLabel, as in the example above, or give EditableInput an aria-label. Give every Editable a placeholder, such as “Add a project name”, so that an empty value still reads. Name the pencil after the value with labels.edit, such as “Rename project”, so that several pencils on one page can be told apart.

Editable suits a value that people read far more often than they change, such as the title of a project or a page, or the name of an item in a list. A settings form keeps its fields open instead, in a Form with one Save for each section, so nothing has to be switched into a field first.

Names in a list

In a list, each name is an Editable of its own. Name each pencil after its item, such as “Rename Open deals”, and save the new name in onValueCommit. With activationMode="none" only the pencil opens the field, so the keyboard reaches one stop per item.

"use client";

import {
  Card,
  CardHeader,
  CardPanel,
  CardTitle,
} from "@/siteplane/components/card";
import {
  Editable,
  EditableArea,
  EditableControl,
  EditableEditTrigger,
  EditableInput,
  EditablePreview,
} from "@/siteplane/components/editable";

const views = ["Open deals", "Renewals this quarter", "My tasks"];

export default function Example() {
  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Saved views</CardTitle>
      </CardHeader>
      <CardPanel>
        <ul className="flex flex-col gap-2">
          {views.map((view) => (
            <li key={view}>
              <Editable
                activationMode="none"
                defaultValue={view}
                labels={{ edit: `Rename ${view}` }}
                required
              >
                <EditableArea>
                  <EditablePreview />
                  <EditableInput aria-label="View name" />
                </EditableArea>
                <EditableControl>
                  <EditableEditTrigger />
                </EditableControl>
              </Editable>
            </li>
          ))}
        </ul>
      </CardPanel>
    </Card>
  );
}

While editing, the root carries data-editing. Give it a width there when its container sizes to its content, such as data-editing:w-80, so the field has room for a longer name.

Validation

Inside a Field, Enter and leaving check the value before they keep it: the native constraints of the field, such as required or type="email", and the Field’s validate. A value that fails stays in its field, and FieldError shows the message under it. Without children, FieldError shows the browser’s message for a native constraint. Escape puts back the saved value and clears the error.

"use client";

import {
  Editable,
  EditableArea,
  EditableControl,
  EditableEditTrigger,
  EditableInput,
  EditablePreview,
} from "@/siteplane/components/editable";
import {
  Field,
  FieldDescription,
  FieldError,
  FieldLabel,
} from "@/siteplane/components/field";

function validateIdentifier(value: unknown) {
  return typeof value === "string" && !/^[A-Z]{2,5}$/.test(value)
    ? "Use 2 to 5 capital letters, such as ENG."
    : null;
}

export default function Example() {
  return (
    <Field className="w-full max-w-sm" validate={validateIdentifier}>
      <FieldLabel>Team identifier</FieldLabel>
      <Editable
        defaultValue="ENG"
        labels={{ edit: "Rename team identifier" }}
        required
      >
        <EditableArea>
          <EditablePreview />
          <EditableInput autoComplete="off" spellCheck={false} />
        </EditableArea>
        <EditableControl>
          <EditableEditTrigger />
        </EditableControl>
      </Editable>
      <FieldDescription>
        Issue IDs start with it, as in ENG-128.
      </FieldDescription>
      <FieldError />
    </Field>
  );
}

Without a Field, the browser shows its own message for a native constraint, and the value stays in its field until it passes.

Multi-line value

EditableTextarea edits text with line breaks. Enter starts a new line, and Cmd+Enter on Apple systems or Ctrl+Enter elsewhere saves. At rest the preview wraps the text and keeps its line breaks, inside the textarea's insets. The textarea keeps the pencil's room at its end, so it wraps the text in the same width and every line breaks where it broke at rest.

"use client";

import {
  Editable,
  EditableArea,
  EditableControl,
  EditableEditTrigger,
  EditablePreview,
  EditableTextarea,
} from "@/siteplane/components/editable";
import { Field, FieldLabel } from "@/siteplane/components/field";

export default function Example() {
  return (
    <Field className="w-full max-w-md">
      <FieldLabel>Description</FieldLabel>
      <Editable
        defaultValue="Plans, briefs and launch notes for the spring campaign."
        labels={{ edit: "Edit description" }}
        placeholder="Add a description"
      >
        <EditableArea>
          <EditablePreview />
          <EditableTextarea minLines={2.5} />
        </EditableArea>
        <EditableControl>
          <EditableEditTrigger />
        </EditableControl>
      </Editable>
    </Field>
  );
}

Controlled

value with onValueChange puts the value in your application, and edit with onEditChange the edit state. onValueChange receives every change, also while typing, and the value that a cancel puts back; keep the saved value from onValueCommit. A controlled edit state only asks: the pencil, Enter, Escape and leaving call onEditChange, and the edit starts or ends once edit changes. finalFocusEl returns focus to another element afterwards, such as the button that started editing.

"use client";

import { useRef, useState } from "react";
import { Button } from "@/siteplane/components/button";
import {
  Editable,
  EditableArea,
  EditableInput,
  EditablePreview,
} from "@/siteplane/components/editable";

export default function Example() {
  const [name, setName] = useState("Q4 launch plan");
  const [editing, setEditing] = useState(false);
  const rename = useRef<HTMLButtonElement>(null);
  return (
    <div className="flex w-full max-w-sm flex-col items-start gap-4">
      <Editable
        activationMode="none"
        edit={editing}
        finalFocusEl={() => rename.current}
        onEditChange={setEditing}
        onValueChange={setName}
        value={name}
      >
        <EditableArea>
          <EditablePreview />
          <EditableInput aria-label="Document name" />
        </EditableArea>
      </Editable>
      <Button
        disabled={editing}
        onClick={() => setEditing(true)}
        ref={rename}
        variant="outline"
      >
        Rename
      </Button>
    </div>
  );
}

The callbacks receive the value itself as their first argument, not an object.

Saving and leaving

submitMode sets what saves a change: both, the default, saves on Enter and when focus or a press leaves the editable; enter saves on Enter alone; blur on leaving alone; and none only with an EditableSubmitTrigger. Where leaving does not save, it cancels. Leaving means a press or a focus move outside the editable and its Field, so the label, the hint and the error belong to it. Focus that moved to another element stays there. Inside a Field, leaving with a value that fails its check keeps the field open with the error.

activationMode sets what opens the field from the preview: focus, the default, opens it when the preview receives focus; click on a click; dblclick on a double click; and none only from the pencil. The preview takes focus only while it can open the field.

Keyboard

API reference

EditableProps extends native div props without defaultValue, onChange and placeholder. Every part accepts a ref and a string className. The root carries data-editing while editing, as well as data-disabled, data-readonly and data-invalid; EditableArea and EditablePreview carry data-placeholder-shown while the value is empty. The triggers are buttons of type button, so they never submit a form. The types EditableLabels, EditablePlaceholder, EditableActivationMode and EditableSubmitMode are exported.

Read the installed source.

Usage notes

Use Editable for a single value shown as text that people rename now and then, such as a project or page title or the name of a list item. Settings forms keep their fields open: compose Input or Textarea in a Field, inside a Form with one Save for each section. A value with more than one part, such as an address, is edited in a Dialog with a form.

Show what the change does near the value, for example with a Toast after onValueCommit saved it, and keep the request and its error state in your application. An error from your server can come back through invalid or the errors of a Form.

Editable has some limits. The field takes the width of the row and does not grow with its text. A click on the FieldLabel does not open the field. There are no props for the ids of the parts, no provider or hook that reads the edit state from outside, and no callbacks for a press or a focus move outside the editable.