Editable

Edit text inline by switching a preview to an input

Usage

Editable displays a value as a preview and switches it to an input for inline editing. The edit is committed on Enter or blur and cancelled on Escape:

Click to edit this text
import { Editable } from '@mantine/core';

function Demo() {
  return <Editable defaultValue="Click to edit this text" activationMode="click" />;
}

Activation mode

activationMode prop controls how the preview enters edit mode:

  • focus (default) – when the preview receives focus (Tab or click)
  • click – on a single click
  • dblclick – on a double click
  • none – only with the controller or with Editable.EditTrigger
Focus to edit (Tab or click)
Click to edit
Double click to edit
import { Editable, Stack } from '@mantine/core';

function Demo() {
  return (
    <Stack maw={320}>
      <Editable defaultValue="Focus to edit (Tab or click)" activationMode="focus" />
      <Editable defaultValue="Click to edit" activationMode="click" />
      <Editable defaultValue="Double click to edit" activationMode="dblclick" />
    </Stack>
  );
}

Submit mode

submitMode prop controls what commits the edit. Escape cancels the edit in all modes:

  • both (default) – Enter and blur
  • enter – only Enter
  • blur – only blur, including when the browser window loses focus
  • none – only the controller or Editable.SubmitTrigger

submitMode="both" (default)

Enter or blur commits

submitMode="enter"

Only Enter commits

submitMode="blur"

Only blur commits
import { Editable, Stack, Text } from '@mantine/core';

function Demo() {
  return (
    <Stack maw={360}>
      <div>
        <Text size="sm" fw={500}>submitMode="both" (default)</Text>
        <Editable defaultValue="Enter or blur commits" activationMode="click" submitMode="both" />
      </div>
      <div>
        <Text size="sm" fw={500}>submitMode="enter"</Text>
        <Editable defaultValue="Only Enter commits" activationMode="click" submitMode="enter" />
      </div>
      <div>
        <Text size="sm" fw={500}>submitMode="blur"</Text>
        <Editable defaultValue="Only blur commits" activationMode="click" submitMode="blur" />
      </div>
    </Stack>
  );
}

Select on focus

By default, the input contents are selected when the field enters edit mode. Set selectOnFocus={false} to place the caret at the end of the value instead:

import { Editable } from '@mantine/core';

function Demo() {
  return <Editable defaultValue="Project name" selectOnFocus={false} />;
}

Placeholder

Set placeholder to display text when the value is empty. It can be a string or an object with preview and edit keys to use different text in each mode:

Click to add a description
import { Editable } from '@mantine/core';

function Demo() {
  return (
    <Editable
      activationMode="click"
      placeholder={{ preview: 'Click to add a description', edit: 'Type a description...' }}
    />
  );
}

Controlled value

Use value and onChange props to control the value. onChange is called on every keystroke, onValueCommit when the edit is confirmed and onValueRevert when it is cancelled:

import { useState } from 'react';
import { Editable } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState('Project name');
  return (
    <Editable
      value={value}
      onChange={setValue}
      onValueCommit={(committed) => console.log('committed', committed)}
      onValueRevert={(reverted) => console.log('reverted to', reverted)}
    />
  );
}

Controlled editing state

Use editing and onEditingChange props to control the editing state. Set defaultEditing to start in edit mode in uncontrolled mode:

import { useState } from 'react';
import { Editable } from '@mantine/core';

function Demo() {
  const [editing, setEditing] = useState(false);
  return <Editable defaultValue="Project name" editing={editing} onEditingChange={setEditing} />;
}

Multiline

Set multiline prop to use a textarea. Enter then inserts a new line and the edit is committed with Cmd/Ctrl + Enter or on blur. Set autosize to grow the field with its content:

A multiline value. Press Cmd/Ctrl + Enter to commit, Escape to cancel.
import { Editable } from '@mantine/core';

function Demo() {
  return (
    <Editable
      multiline
      autosize
      minRows={2}
      activationMode="click"
      defaultValue={'A multiline value.\nPress Cmd/Ctrl + Enter to commit,\nEscape to cancel.'}
      style={{ width: 360 }}
    />
  );
}

useEditable hook

Editable supports the controller pattern with the useEditable hook:

import { useEditable } from '@mantine/core';

function Demo() {
  const controller = useEditable({ defaultValue: 'Project name' });

  controller.getValue(); // -> current value
  controller.isEditing(); // -> boolean, true while the field is in edit mode

  controller.edit(); // enters edit mode
  controller.submit(); // commits the edit, calls onValueCommit
  controller.cancel(); // reverts the value to the one it had when editing started, calls onValueRevert
  controller.setValue('New value'); // updates the value

  return null;
}

useEditable options

useEditable accepts an options object typed as EditableControllerOptions:

interface EditableControllerOptions {
  /** Controlled value */
  value?: string;

  /** Initial uncontrolled value */
  defaultValue?: string;

  /** Called on every value change */
  onChange?: (value: string) => void;

  /** Called on submit, even if the value did not change */
  onValueCommit?: (value: string) => void;

  /** Called when the edit is cancelled */
  onValueRevert?: (value: string) => void;

  /** Controlled editing state */
  editing?: boolean;

  /** Initial uncontrolled editing state, false by default */
  defaultEditing?: boolean;

  /** Called when the editing state changes */
  onEditingChange?: (editing: boolean) => void;

  /** How the preview enters edit mode, 'focus' by default */
  activationMode?: 'focus' | 'click' | 'dblclick' | 'none';

  /** What confirms the edit, 'both' by default */
  submitMode?: 'both' | 'enter' | 'blur' | 'none';

  /** Selects the input contents when entering edit mode, true by default */
  selectOnFocus?: boolean;

  /** Prevents entering edit mode, false by default */
  disabled?: boolean;

  /** Prevents changing the value, false by default */
  readOnly?: boolean;
}

Controlling with useEditable

Pass the controller to the controller prop. The options accepted by useEditable are then ignored on Editable, pass them to the hook instead.

Buttons outside of Editable that call submit or cancel must call event.preventDefault() in onMouseDown, otherwise blur commits the edit before the click is handled:

Controlled by the hook

Value: Controlled by the hook — editing: no

import { Button, Editable, Group, Stack, Text, useEditable } from '@mantine/core';

const preventBlur = (event: React.MouseEvent) => event.preventDefault();

function Demo() {
  const controller = useEditable({ defaultValue: 'Controlled by the hook' });

  return (
    <Stack maw={360}>
      <Editable controller={controller} />

      <Group>
        <Button size="xs" variant="default" onMouseDown={preventBlur} onClick={controller.edit}>
          Edit
        </Button>
        <Button size="xs" variant="default" onMouseDown={preventBlur} onClick={controller.submit}>
          Submit
        </Button>
        <Button size="xs" variant="default" onMouseDown={preventBlur} onClick={controller.cancel}>
          Cancel
        </Button>
      </Group>

      <Text size="sm">
        Value: {controller.getValue()} — editing: {controller.isEditing() ? 'yes' : 'no'}
      </Text>
    </Stack>
  );
}

Custom layout

Pass compound components as children to change the layout. Triggers are displayed only in the relevant mode: the edit trigger in preview mode, the submit and cancel triggers in edit mode. Use Editable.Textarea instead of Editable.Input for multiline values:

Project name
import { ActionIcon, Editable, Group } from '@mantine/core';
import { CheckIcon, PencilSimpleIcon, XIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <Editable defaultValue="Project name" activationMode="none">
      <Group gap="xs">
        <Editable.Preview />
        <Editable.Input />
        <Editable.Control>
          <Editable.EditTrigger aria-label="Edit">
            <ActionIcon component="span" variant="default">
              <PencilSimpleIcon size={16} />
            </ActionIcon>
          </Editable.EditTrigger>
          <Editable.SubmitTrigger aria-label="Save">
            <ActionIcon component="span" variant="default">
              <CheckIcon size={16} />
            </ActionIcon>
          </Editable.SubmitTrigger>
          <Editable.CancelTrigger aria-label="Cancel">
            <ActionIcon component="span" variant="default">
              <XIcon size={16} />
            </ActionIcon>
          </Editable.CancelTrigger>
        </Editable.Control>
      </Group>
    </Editable>
  );
}

Editable with uncontrolled forms

Set name to include the value in native form submission.

In preview mode the value is submitted with a hidden input, so required is enforced only in edit mode. Validate the value yourself if it must not be empty.

import { Button, Editable } from '@mantine/core';

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        console.log(data.get('title'));
      }}
    >
      <Editable
        name="title"
        aria-label="Title"
        defaultValue="Untitled document"
        maxLength={100}
      />
      <Button type="submit" mt="md">Save</Button>
    </form>
  );
}

Focus management

When the edit is committed or cancelled with the keyboard or triggers, focus returns to the preview. Set finalFocusRef to move focus to a different element instead. Moving focus to a trigger inside Editable does not commit the edit:

import { useRef } from 'react';
import { Button, Editable, Group } from '@mantine/core';

function Demo() {
  const nextRef = useRef<HTMLButtonElement>(null);

  return (
    <Group>
      <Editable defaultValue="Project name" finalFocusRef={nextRef} />
      <Button ref={nextRef}>Next step</Button>
    </Group>
  );
}

Accessibility

The preview is a focusable button named by its text. If the value can be empty and placeholder is not set, set aria-label on Editable:

import { Editable } from '@mantine/core';

function Demo() {
  return <Editable aria-label="Project name" />;
}

When a trigger renders only an icon, set an aria-label:

import { Editable } from '@mantine/core';

function Demo() {
  return (
    <Editable defaultValue="Project name" activationMode="none">
      <Editable.Preview />
      <Editable.Input />
      <Editable.EditTrigger aria-label="Edit name">✎</Editable.EditTrigger>
      <Editable.SubmitTrigger aria-label="Save">✓</Editable.SubmitTrigger>
      <Editable.CancelTrigger aria-label="Cancel">✕</Editable.CancelTrigger>
    </Editable>
  );
}