# Editable
Package: @mantine/core
Import: import { Editable } from '@mantine/core';
Description: 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`:

```tsx
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`

```tsx
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`

```tsx
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:

```tsx
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:

```tsx
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:

```tsx
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:

```tsx
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:

```tsx
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](https://alpha.mantine.dev/llms/guides-controllers.md) with the `useEditable` hook:

```tsx
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`:

```ts
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:

```tsx
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:

```tsx
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.

```tsx
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:

```tsx
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`:

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

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

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

```tsx
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>
  );
}
```


#### Props

**Editable props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| activationMode | EditableActivationMode | - | How the preview enters edit mode, `'focus'` by default |
| autosize | boolean | - | If set, the `textarea` grows to fit its content, `false` by default. Only used when `multiline` is set |
| children | React.ReactNode | - | Custom layout built with `Editable.Preview`, `Editable.Input` and other compound components |
| controller | EditableController | - | Controller returned by the `useEditable` hook. When provided, the editing state is controlled externally and these props are ignored: `value`, `defaultValue`, `onChange`, `onValueCommit`, `onValueRevert`, `editing`, `defaultEditing`, `onEditingChange`, `activationMode`, `submitMode`, `selectOnFocus`, `disabled` and `readOnly` – pass them to `useEditable` instead |
| defaultEditing | boolean | - | Uncontrolled editing state initial value, `false` by default |
| defaultValue | string | - | Uncontrolled value initial state |
| disabled | boolean | - | If set, entering edit mode is disabled, `false` by default |
| editing | boolean | - | Controlled editing state |
| finalFocusRef | RefObject<HTMLElement \| null> | - | Element focused when edit mode is exited with the keyboard or a trigger click. Defaults to the preview, or to the first focusable element inside `Editable` when the preview is not focusable |
| maxLength | number | - | Maximum length of the value |
| maxRows | number | - | Maximum `textarea` rows to grow to, only used with `autosize` |
| minRows | number | - | Minimum `textarea` rows, only used with `autosize` |
| multiline | boolean | - | If set, a `textarea` is used instead of an `input`, `false` by default |
| name | string | - | `name` attribute of the input, used for form submission |
| onChange | (value: string) => void | - | Called on every value change (on each keystroke) |
| onEditingChange | (editing: boolean) => void | - | Called when the editing state changes |
| onValueCommit | (value: string) => void | - | Called when the edit is confirmed, on every submit even when the value did not change |
| onValueRevert | (value: string) => void | - | Called when the edit is cancelled |
| placeholder | string \| EditablePlaceholder | - | Placeholder text displayed when the value is empty. Can be a string or an object with `edit` and `preview` keys |
| readOnly | boolean | - | If set, the value cannot be changed, `false` by default |
| required | boolean | - | Adds `required` attribute to the input |
| selectOnFocus | boolean | - | If set, the input contents are selected when entering edit mode, `true` by default |
| submitMode | EditableSubmitMode | - | What confirms the edit, `'both'` by default |
| value | string | - | Controlled value |

**Editable.Area props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|

**Editable.Preview props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|

**Editable.Input props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|

**Editable.Textarea props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|

**Editable.Control props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|

**Editable.EditTrigger props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|

**Editable.SubmitTrigger props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|

**Editable.CancelTrigger props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|


#### Styles API

Editable component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**Editable selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-Editable-root | Root element |
| area | .mantine-Editable-area | Editable.Area element, an optional wrapper of the preview and input |
| preview | .mantine-Editable-preview | Editable.Preview element, displays the value in read mode |
| input | .mantine-Editable-input | Editable.Input and Editable.Textarea element, the field displayed in edit mode |
| control | .mantine-Editable-control | Editable.Control element, a wrapper of the triggers |
| editTrigger | .mantine-Editable-editTrigger | Editable.EditTrigger element, a button that enters edit mode |
| submitTrigger | .mantine-Editable-submitTrigger | Editable.SubmitTrigger element, a button that commits the edit |
| cancelTrigger | .mantine-Editable-cancelTrigger | Editable.CancelTrigger element, a button that cancels the edit |

**Editable data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| preview | data-empty | Value is empty | - |
| preview | data-disabled | `disabled` prop is set | - |
| preview | data-read-only | `readOnly` prop is set | - |
| preview | data-multiline | `multiline` prop is set | - |
