InputsReact

Editable

A text shown in place that turns into a field when pressed.

Rendered by React 19.3.1

Loading React…

import * as React from 'react'
import { Editable } from '@hamur/react/editable'
import { Field } from '@hamur/react/field'

export default function EditableExample() {
  const [name, setName] = React.useState('Ada Lovelace')
  return (
    <Field.Root className="field">
      <Field.Label>Display name</Field.Label>
      <Editable.Root
        className="editable"
        value={name}
        placeholder="Add a display name"
        onValueChange={(next: string) => setName(next)}
      >
        <Editable.Preview className="editable-preview" />
        <Editable.Input className="editable-input" />
      </Editable.Root>
      <Field.Description className="muted">
        Press the name to edit it; Enter saves and Escape cancels.
      </Field.Description>
    </Field.Root>
  )
}

Not measured yetTests passing in React

Not measured yetSize

Not measured yetMemory

Not measured yetSpeed

[N] commits

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<Editable.Root>
  <Editable.Preview />
  <Editable.Input />
</Editable.Root>

// Not in this example: Editable.CancelTrigger, Editable.EditTrigger, Editable.SubmitTrigger

Examples

Multiline

A bio in a textarea with autoResize: Enter types a line break, Control+Enter or Meta+Enter saves, and the Preview keeps the line breaks.

EditableMultiline.tsx

import * as React from 'react'
import { Editable } from '@hamur/react/editable'
import { Field } from '@hamur/react/field'

export default function EditableMultilineExample() {
  const [bio, setBio] = React.useState(
    'Mathematician and writer.\nWrote the first published program.',
  )
  return (
    <Field.Root className="field">
      <Field.Label>Bio</Field.Label>
      <Editable.Root
        className="editable"
        value={bio}
        autoResize
        placeholder="Add a bio"
        onValueChange={(next: string) => setBio(next)}
      >
        <Editable.Preview className="editable-preview" />
        <Editable.Input className="editable-input" render={<textarea />} />
      </Editable.Root>
      <Field.Description className="muted">
        Enter adds a line; Ctrl+Enter or Cmd+Enter saves and Escape cancels.
      </Field.Description>
    </Field.Root>
  )
}

Triggers

A project title with activationMode="dblclick": a double-click or the EditTrigger starts an edit, and the SubmitTrigger and CancelTrigger end it.

EditableTriggers.tsx

import * as React from 'react'
import { Editable } from '@hamur/react/editable'
import { Field } from '@hamur/react/field'

export default function EditableTriggersExample() {
  const [title, setTitle] = React.useState('Quarterly report')
  return (
    <Field.Root className="field">
      <Field.Label>Project</Field.Label>
      <Editable.Root
        className="editable"
        value={title}
        activationMode="dblclick"
        onValueChange={(next: string) => setTitle(next)}
      >
        <Editable.Preview className="editable-preview" />
        <Editable.Input className="editable-input" />
        <Editable.EditTrigger className="editable-trigger">
          <svg className="editable-icon" viewBox="0 0 16 16" aria-hidden="true">
            <path d="M11 2.5l2.5 2.5L6 12.5H3.5V10z" />
          </svg>
        </Editable.EditTrigger>
        <Editable.SubmitTrigger className="editable-trigger">
          <svg className="editable-icon" viewBox="0 0 16 16" aria-hidden="true">
            <path d="M3 8.5l3 3 7-7" />
          </svg>
        </Editable.SubmitTrigger>
        <Editable.CancelTrigger className="editable-trigger">
          <svg className="editable-icon" viewBox="0 0 16 16" aria-hidden="true">
            <path d="M4 4l8 8M12 4l-8 8" />
          </svg>
        </Editable.CancelTrigger>
      </Editable.Root>
      <Field.Description className="muted">
        Double-click the title, or press Edit, to rename it.
      </Field.Description>
    </Field.Root>
  )
}

Form

A username in a Form: required refuses an empty save, cancel() in onValueChange refuses other characters, and the hidden input submits the text.

EditableForm.tsx

import * as React from 'react'
import { Editable } from '@hamur/react/editable'
import { Field } from '@hamur/react/field'
import { Form } from '@hamur/react/form'

const USERNAME = /^[a-z0-9-]+$/

export default function EditableFormExample() {
  const [username, setUsername] = React.useState('')
  const [refused, setRefused] = React.useState('')
  const [submitted, setSubmitted] = React.useState('')
  return (
    <Form
      className="stack"
      onFormSubmit={(_values, details) => {
        const form = details.event.target as HTMLFormElement
        setSubmitted([...new FormData(form)].map(([key, value]) => `${key}=${value}`).join('&'))
      }}
    >
      <Field.Root name="username" className="field">
        <Field.Label>Username</Field.Label>
        <Editable.Root
          className="editable"
          value={username}
          required
          placeholder="Choose a username"
          onValueChange={(next: string, details: { cancel: () => void }) => { if (!USERNAME.test(next)) { details.cancel() setRefused('Use lowercase letters, digits and hyphens.') return } setUsername(next) setRefused('') }}
        >
          <Editable.Preview className="editable-preview" />
          <Editable.Input className="editable-input" />
        </Editable.Root>
        <Field.Description className="muted">
          Lowercase letters, digits and hyphens.
        </Field.Description>
        {refused ? <p className="error">{refused}</p> : null}
        <Field.Error className="error" match="valueMissing">
          Choose a username.
        </Field.Error>
      </Field.Root>
      <button className="button" type="submit">
        Save
      </button>
      {submitted ? <pre className="output">{submitted}</pre> : null}
    </Form>
  )
}

API reference

25 props across 6 parts, in React syntax. className, style, render are listed once, under Shared props.

CancelTrigger`Editable.CancelTrigger`

A button that ends the edit without a commit, rendered while editing. Pressing it keeps focus in the Input until it acts. Named "Cancel" and the Field label. Renders a <button>.

CancelTrigger props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`

CancelTrigger data attributes
Data attribute	Description
`data-disabled`	Present when the trigger is disabled.

EditTrigger`Editable.EditTrigger`

A button that starts an edit, rendered while not editing. While it is mounted it is the component's tab stop, and the Preview leaves the tab order. Named "Edit" and the Field label. Renders a <button>.

EditTrigger props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`

EditTrigger data attributes
Data attribute	Description
`data-disabled`	Present when the trigger is disabled.

Input`Editable.Input`

The text field that edits the value, rendered while editing in place of the Preview. Enter commits and Escape cancels; render={<textarea />} makes it multiline, where Ctrl+Enter or Cmd+Enter commits. Renders an <input>.

Input data attributes
Data attribute	Description
`data-editing`	Present while the Input is shown.
`data-empty`	Present when the value is empty.
`data-disabled`	Present when the component is disabled.
`data-readonly`	Present when the component is read-only.
`data-required`	Present when the value may not be empty.
`data-autoresize`	Present when the Input is sized to its content.
`data-valid`	Present when the field is valid.
`data-invalid`	Present when the field is invalid.
`data-dirty`	Present when the value has changed.
`data-touched`	Present when focus has left the component.
`data-filled`	Present when the value is not empty.
`data-focused`	Present while focus is inside the component.
`data-rejected`	Present from a refused commit until the text changes.

Preview`Editable.Preview`

The value shown as a button that starts an edit, or the placeholder while the value is empty. Rendered while not editing. With activationMode="none" it is plain text. Renders a <span>.

Preview props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`false`

Preview data attributes
Data attribute	Description
`data-editing`	Present while the Input is shown.
`data-empty`	Present when the value is empty.
`data-disabled`	Present when the component is disabled.
`data-readonly`	Present when the component is read-only.
`data-required`	Present when the value may not be empty.
`data-autoresize`	Present when the Input is sized to its content.
`data-valid`	Present when the field is valid.
`data-invalid`	Present when the field is invalid.
`data-dirty`	Present when the value has changed.
`data-touched`	Present when focus has left the component.
`data-filled`	Present when the value is not empty.
`data-focused`	Present while focus is inside the component.

Root`Editable.Root`

Groups all parts of the editable: a text shown as a button that turns into a text field to edit it in place. with the hidden inputs, followed by the status region. Renders a <div>.

Root props
Prop	Type	Default
`value`The committed text.	`string`	`—`
`defaultValue`The committed text when the component is initially rendered.	`string`	`—`
`onValueChange`Event handler called once per commit that changes the text.	`((value: string, eventDetails: EditableRootChangeEventDetails) => void)`	`—`
`inputValue`The text in the Input while editing.	`string`	`—`
`onInputValueChange`Event handler called when the text in the Input changes, and with the value when an edit	`((inputValue: string, eventDetails: EditableRootInputValueChangeEventDetails) => void)`	`—`
`editing`Whether the Input is shown.	`boolean`	`—`
`defaultEditing`Whether the Input is shown when the component is initially rendered.	`boolean`	`false`
`onEditingChange`Event handler called when an edit starts or ends.	`((editing: boolean, eventDetails: EditableRootEditingChangeEventDetails) => void)`	`—`
`activationMode`What starts an edit from the Preview: a click, a double-click, focus, or nothing (only the	`EditableActivationMode`	`'click'`
`submitMode`What commits the draft: Enter, focus leaving the component, both, or neither (only the	`EditableSubmitMode`	`'both'`
`selectOnFocus`Whether the text is selected when an edit starts; otherwise the caret goes to the end.	`boolean`	`true`
`placeholder`The Preview's text while the value is empty, and the Input's `placeholder` unless it sets	`string`	`—`
`autoResize`Whether the Input is sized to its content.	`boolean`	`false`
`finalFocus`Where focus goes after an edit ends by a key, a trigger or `actionsRef`: `true` the Preview	`boolean \| React.RefObject<HTMLElement \| null> \| (() => HTMLElement \| null \| undefined)`	`—`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`readOnly`Whether the user should be unable to start an edit.	`boolean`	`false`
`required`Whether the value may not be empty.	`boolean`	`false`
`name`Identifies the field when a form is submitted.	`string`	`—`
`form`Identifies the form that owns the hidden inputs.	`string`	`—`
`actionsRef`A ref to start, commit or cancel an edit from the app.	`React.RefObject<EditableRootActions \| null>`	`—`
`labels`The texts, in English by default: the triggers' names and the refusal announcement.	`Partial<EditableLabels>`	`—`

Root data attributes
Data attribute	Description
`data-editing`	Present while the Input is shown.
`data-empty`	Present when the value is empty.
`data-disabled`	Present when the component is disabled.
`data-readonly`	Present when the component is read-only.
`data-required`	Present when the value may not be empty.
`data-autoresize`	Present when the Input is sized to its content.
`data-valid`	Present when the field is valid.
`data-invalid`	Present when the field is invalid.
`data-dirty`	Present when the value has changed.
`data-touched`	Present when focus has left the component.
`data-filled`	Present when the value is not empty.
`data-focused`	Present while focus is inside the component.

SubmitTrigger`Editable.SubmitTrigger`

A button that commits the draft, rendered while editing. Pressing it keeps focus in the Input until it acts. Named "Save" and the Field label. Renders a <button>.

SubmitTrigger props
Prop	Type	Default
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`true`

SubmitTrigger data attributes
Data attribute	Description
`data-disabled`	Present when the trigger is disabled.

Shared props

Every part that renders an element takes these.

Shared props
Prop	Type
`className`CSS class applied to the element, or a function that returns a class based on the component's state.	`string \| ((state: State) => string \| undefined)`
`style`Style applied to the element, or a function that returns a style object based on the component's state.	`React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined)`
`render`Allows you to replace the component's HTML element with a different tag, or compose it with another component.	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, State>`

Keyboard and accessibility

Keyboard

Keyboard
Keys	Does	Part
`EnterSpace`	Starts an edit, with the text selected	Preview
`Enter`	Saves the text once, and does not submit the form	Input
`ControlEnter`	In a textarea, saves the text; Enter alone types a line break	Input
`Escape`	Cancels the edit and restores the text	Input
`Tab`	Leaving the Root saves the text; moving to Save or Cancel does not	Input
`EnterSpace`	Starts an edit	EditTrigger
`EnterSpace`	Saves the text	SubmitTrigger
`EnterSpace`	Cancels the edit and restores the text	CancelTrigger

Accessibility

What the parts set
Part	Sets	So that
Preview	a `span` with `role="button"`, named by the Field label and its own text, and described by the Field's description and error	a reader hears "Display name Ada Lovelace, button" and knows a press edits it
Preview	with `activationMode="none"`, no role and no `tabindex`	text that only the EditTrigger edits is read as text, not as a button that does nothing
Input	an `input` of type `text`, or a `textarea`, named by the Field label; `aria-invalid` while a save is refused	the field is read with its label, and a refused save is heard on the field
EditTrigger	a `button` named "Edit" and the Field label; while it is shown it is the Tab stop and the Preview is at `tabindex="-1"`	the component is one Tab stop, and the button says what it edits
SubmitTrigger	a `button` named "Save" and the Field label; a mousedown on it is prevented	a press saves without first moving focus out of the Input
CancelTrigger	a `button` named "Cancel" and the Field label; a mousedown on it is prevented	a press cancels without first saving on blur
Root	one polite `role="status"` region after the Root, and with a `name` a hidden input with the committed text	a refused save is announced ("Not saved", or the Input's own message), and the form gets it

Focus order

The Preview is the Tab stop, or the EditTrigger when there is one; Tab onto the Preview starts nothing unless activationMode is focus.
While editing, the Input takes focus with its text selected, then Save and Cancel follow it in the Tab order.
Focus leaving the Root saves the text, and Enter, Escape and the triggers return focus to the Tab stop.