Skip to content

OrigamInlineEdit ​

Edit-in-place pattern. The user clicks a label / title / cell, an input appears prefilled with the current value, and Enter confirms while Escape cancels. Common use cases: renaming a section header, editing a card title, tweaking a label in a list — anywhere a full modal form would feel heavy.

vue
<template>
    <origam-inline-edit
            v-model="title"
            placeholder="Untitled"
            :validate="(v) => v.length >= 3 || 'Min 3 chars'"
    />
</template>

When no #display slot is provided, the component renders a native <button> carrying the current value (or the placeholder when the value is empty). When no #edit slot is provided, it renders an <OrigamTextField> (or <OrigamTextareaField> when multiline is true). When showActions=true, the Confirm and Cancel buttons are placed inside the field via its appendInner slot.

Quick start ​

vue
<origam-inline-edit v-model="userName" placeholder="Full name" />

<origam-inline-edit
        v-model="description"
        :multiline="true"
        :confirm-on-enter="false"
        placeholder="Add a description"
/>

<origam-inline-edit
        v-model="email"
        input-type="email"
        :validate="(v) => /^.+@.+\..+$/.test(v) || 'Invalid email'"
/>

Props — Typography ​

These props set CSS custom properties on the root element so they cascade to the BEM surfaces that read them. Only props with a real visual effect are exposed — fontFamily, letterSpacing and lineHeight were removed from IInlineEditProps (issue #501); no rule in the SCSS read any of them.

PropTypeValuesEffect
fontSizeTFontSizexs · sm · md · lg · xl · 2xl · 3xl · 4xl · 5xl--origam-inline-edit__error---font-size (error message) and --origam-inline-edit__action-btn---font-size (action buttons)
fontWeightTFontWeightregular · medium · semibold · bold · extrabold · black--origam-inline-edit__error---font-weight (error message only — action-btn weight is hardcoded 600)

Props ​

PropTypeDefaultNotes
modelValuestring | numberrequiredv-model target. Numbers round-trip as numbers.
placeholderstringorigam.inline_edit.placeholderShown on the input and on the empty display. Unset, it resolves through the DS locale ("Click to edit" in English).
rulesArray<(v: string) => true | string | Promise<…>>undefinedArray of validation rules — same contract as all DS form fields. Rules are evaluated sequentially; first failure surfaces the error and blocks the commit. Evaluated before validate.
validate(v: string) => true | string | Promise<…>undefinedSync or async validator. Returning a string surfaces it as an error and keeps the editor open. Only runs if all rules pass.
autoFocusbooleantrueAuto-focus the input on edit entry.
selectOnFocusbooleantrueSelect all text after auto-focus.
confirmOnBlurbooleantrueCommit when focus leaves the component. Moving focus between the field and the built-in Confirm / Cancel buttons is not leaving. Disable to require an explicit Enter / button. See "Combining showActions and confirmOnBlur".
confirmOnEnterbooleantrueConfirm on Enter. In multiline mode, this becomes Cmd/Ctrl+Enter.
cancelOnEscapebooleantrueRevert on Escape.
disabledbooleanfalseDisplay becomes non-interactive; edit() short-circuits.
multilinebooleanfalseRender a <textarea> instead of <input>.
trimbooleantrueStrip surrounding whitespace before validate + emit.
inputType'text' | 'number' | 'email' | 'tel''text'Native HTML input type in single-line mode.
loadingOnConfirmbooleanfalseAdds a CSS hook (.origam-inline-edit--loading-on-confirm) while a Promise validator is in flight. aria-busy is set regardless.
showActionsbooleanfalseRender built-in Edit / Confirm / Cancel buttons. See "Action buttons" section below.
tagstring'div' (was 'span' before 2026-09)Root element tag. See "Migration — tag default changed" below if you relied on the old default.
idstringundefinedForwarded to the root element.
classstring | Array | objectundefinedMerged onto the root element alongside the state classes.
stylestring | Array | objectundefinedMerged onto the root element alongside the typography vars.

Localisation ​

Every user-facing string this component renders itself goes through the DS locale provider (useLocale), so createOrigam() must be installed — which it already had to be, since edit mode renders OrigamTextField.

KeyEnglish
origam.inline_edit.placeholderClick to edit
origam.inline_edit.edit_aria_labelEdit {0} — display affordance
origam.inline_edit.editEdit — the pencil action button
origam.inline_edit.confirmConfirm
origam.inline_edit.cancelCancel
origam.inline_edit.field_aria_labelEdit value — accessible name of the input
origam.inline_edit.invalid_valueInvalid value — validator rejected without its own message

Migration — tag default changed from 'span' to 'div' ​

Since 2026-09, the root element defaults to <div> instead of <span>.

Why: edit mode renders <OrigamTextField> / <OrigamTextareaField>, both of which render a <div> internally (OrigamField). A <div> is flow content, not phrasing content, so a <span> root could never legally contain it — the previous default produced invalid HTML on every instance that entered edit mode. .origam-inline-edit { display: inline-flex } already forces the inline-level box regardless of the underlying tag, so this change has no visual effect — dimensions, position and computed display are identical between the two tags (verified in a real browser, not jsdom; see packages/tests/e2e/inline-edit-tag.spec.ts).

Action required — only if you placed <origam-inline-edit> inside a phrasing-content-only ancestor (a <p>, a <label>, another <span>, …): pass tag="span" explicitly to keep the previous behaviour.

vue
<!-- Before 2026-09, this relied on the implicit 'span' default -->
<p>
    Status: <origam-inline-edit v-model="status" tag="span" />
</p>

If you don't do this, a <div> inside a <p> closes the paragraph implicitly wherever the browser's HTML parser is involved (raw HTML text, or SSR markup parsed on page load) — the surrounding content can be reordered. The tag prop itself is unchanged; only its default value moved.

Emits ​

EmitPayloadWhen
update:modelValue(value)After successful validation. Preserves the v-model shape (string vs number).
edit—Editor entered edit mode (display → input transition).
cancel—Editor exited via Esc / cancel — the draft was discarded.
confirm(value)Fires AFTER validation passes, BEFORE update:modelValue. Useful for server-side persistence.
validate-error(message: string)Validator returned an error message (sync or async).

Slots scoped ​

#display — { value, edit, isEmpty, placeholder, disabled } ​

Render any affordance you like (heading, badge, list-item cell, …). Call edit() to enter edit mode.

vue
<origam-inline-edit v-model="title">
    <template #display="{ value, edit, isEmpty, placeholder }">
        <h2 :class="{ 'is-empty': isEmpty }" @click="edit">
            {{ isEmpty ? placeholder : value }}
        </h2>
    </template>
</origam-inline-edit>

#edit — { value, setValue, confirm, cancel, error, isPending } ​

Render any custom input layout. Wire keyboard handlers yourself — the slot is a complete take-over.

vue
<template #edit="{ value, setValue, confirm, cancel, error }">
    <input
        :value="value"
        @input="setValue(($event.target as HTMLInputElement).value)"
        @keydown.enter.prevent="confirm()"
        @keydown.esc.prevent="cancel()"
    >
    <span v-if="error" role="alert">{{ error }}</span>
</template>

#actions — { confirm, cancel, isPending } ​

Render custom confirm / cancel buttons. When showActions=true, the slot content is placed inside the field's appendInner slot (after the text area). When showActions=false, the slot is not rendered unless you provide it explicitly — in which case it renders as a sibling of the field. Use @mousedown.prevent on the buttons when confirmOnBlur=true to prevent the input blur from triggering an unwanted commit before the click fires.

Action buttons ​

By default, OrigamInlineEdit is keyboard-driven: click the display to enter edit mode, press Enter to confirm, Escape to cancel. This is intentional for power users and data-dense UIs.

For mouse-first or touch-first contexts, pass showActions to render three built-in icon buttons:

vue
<origam-inline-edit
    v-model="title"
    :show-actions="true"
    :confirm-on-blur="false"
    placeholder="Click to edit"
/>

Behaviour with showActions=true ​

ModeButtons visibleButton hidden
DisplayEdit (✎) next to the display labelConfirm, Cancel
EditConfirm (✓), Cancel (✕) inside the fieldEdit
  • Clicking Edit is equivalent to clicking the display affordance.
  • Clicking Confirm is equivalent to pressing Enter.
  • Clicking Cancel is equivalent to pressing Escape.
  • Keyboard shortcuts (Enter / Escape) continue to work in parallel — showActions is purely additive.
  • When disabled is true, all three buttons are also disabled.

DOM structure in edit mode ​

When showActions=true, the Confirm and Cancel buttons are rendered inside the field via the appendInner slot of OrigamTextField (or OrigamTextareaField in multiline mode). They are not siblings of the field element. This guarantees visual alignment and prevents layout overflow issues when the component is used in constrained containers.

html
<!-- single-line (showActions=true, isEditing=true) -->
<div class="origam-inline-edit origam-inline-edit--editing origam-inline-edit--show-actions">
  <div class="origam-text-field origam-inline-edit__field" data-cy="origam-inline-edit-input">
    <!-- OrigamTextField internals -->
    <div class="origam-field__append-inner">
      <button data-cy="origam-inline-edit-action-confirm">&#10003;</button>
      <button data-cy="origam-inline-edit-action-cancel">&#10005;</button>
    </div>
  </div>
</div>

Combining showActions and confirmOnBlur ​

Since #614, no workaround is needed: the two props compose.confirmOnBlur commits when focus leaves the component, not when it leaves the input, so tabbing from the field onto Confirm or Cancel keeps edit mode open and both buttons reachable. Tabbing past them — out of the component — still commits, which is what the prop promises.

vue
<!-- both defaults, nothing to disable -->
<origam-inline-edit
    v-model="label"
    :show-actions="true"
/>

Set :confirm-on-blur="false" only when you genuinely want leaving the component to discard rather than commit.

What this replaced ​

confirmOnBlur used to listen to @blur on the field and commit without looking at where focus was going. A single Tab therefore left edit mode and unmounted Confirm and Cancel before focus could reach them — measured in Chromium:

entering edit mode   document.activeElement = input   Confirm present
Tab #1               document.activeElement = body    Confirm GONE
Tab #2               document.activeElement = the display affordance

Mouse users never hit it, because the built-in buttons carry @mousedown.prevent — which stops the blur before the click. There was no keyboard equivalent of that guard, so the old advice was to turn confirmOnBlur off. That advice is obsolete.

Two side effects of the same shape were fixed with it:

  • Enter on Cancel used to confirm: the button's keydown bubbled into the field's own Enter shortcut (measured — the draft was committed instead of discarded). Field shortcuts now only act on events coming from the input itself.
  • Space on either button did nothing: the field's appendInner zone called preventDefault() on Enter / Space bubbling up from real controls rendered inside it, killing their native activation. That zone now only claims keys targeted at itself.

After Confirm or Cancel, focus returns to the display affordance instead of falling back to <body>.

The built-in buttons still use @mousedown.prevent internally to avoid stealing focus from the input before the click handler runs.

Using the #actions slot instead ​

If you need a fully custom button layout, use the #actions slot — it takes precedence over the built-in buttons even when showActions is true. The slot is only rendered while in edit mode:

vue
<origam-inline-edit v-model="label" :confirm-on-blur="false">
    <template #actions="{ confirm, cancel, isPending }">
        <button :disabled="isPending" @mousedown.prevent @click="confirm()">Save</button>
        <button @mousedown.prevent @click="cancel()">Discard</button>
    </template>
</origam-inline-edit>

Validation patterns ​

Sync — instantaneous verdict ​

ts
const validate = (v: string): true | string =>
    v.length >= 3 || 'Min 3 chars'

Async — server-side uniqueness check ​

ts
const validate = async (v: string): Promise<true | string> => {
    const taken = await api.checkAvailability(v)
    return taken ? `"${v}" is already taken` : true
}

While the Promise is in flight, the component sets aria-busy="true" on the root and the real disabled attribute on the input (not aria-disabled — the control is genuinely inert while validating). With loadingOnConfirm=true, an additional CSS hook is exposed so you can render a spinner overlay if needed.

Rules array — standard DS contract ​

vue
<origam-inline-edit
    v-model="title"
    :rules="[
        (v) => v.trim().length > 0 || 'Value cannot be empty',
        (v) => v.length >= 5   || 'Min 5 characters required',
    ]"
/>

Rules follow the same signature as OrigamTextField / OrigamInput rules: a function receiving the current string value and returning true (pass) or an error message string (fail). Async rules (returning a Promise) are supported.

Coexistence of rules and validate ​

Both props can be used simultaneously. Evaluation order:

  1. rules are evaluated first, sequentially. The first failing rule stops evaluation and surfaces its message.
  2. validate is only called if all rules pass.

Only the first error message is ever displayed — the editor remains open and the commit is blocked until the value satisfies both.

vue
<origam-inline-edit
    v-model="email"
    :rules="[
        (v) => v.trim().length > 0 || 'Required',
        (v) => v.includes('@')     || 'Must contain @',
    ]"
    :validate="async (v) => {
        const taken = await api.checkEmail(v)
        return taken ? 'Email already in use' : true
    }"
/>

Error UX ​

When the validator returns a string, the component:

  • Keeps the editor open so the user can correct without re-clicking.
  • Renders the message inside a <span role="alert"> so screen readers announce it immediately.
  • Sets aria-invalid="true" on the input.
  • Clears the error as soon as the user types again (the next validation cycle starts fresh).

Accessibility ​

  • Display affordance — the default render is a native <button> with an aria-label of "Edit {value or placeholder}". Keyboard users get focus / Enter / Space semantics for free.
  • Edit affordance — the native <input> / <textarea> carries an aria-label (origam.inline_edit.field_aria_label) so it always has an accessible name. It is additionally decorated with aria-invalid and aria-describedby (pointing to the inline error) when a validator fails. Before this was wired, the only naming source was the placeholder — the last-resort branch of the accessible-name algorithm, which yields no name at all under placeholder="".
  • Action buttons — with showActions, the display affordance and the pencil button both enter edit mode. The pencil carries tabindex="-1" and aria-hidden="true": it stays visible and clickable for mouse users, but leaves the keyboard path, where the display affordance already exposes the same action. Nothing disappears on screen, and a keyboard user no longer tabs twice through one command. Their accessible names remain deliberately different (Edit {value} and Edit) as a net for a consumer who strips aria-hidden. Confirm and Cancel are keyboard reachable — Tab from the field lands on Confirm, then Cancel — and actionable with both Enter and Space.

    ⚠️ This paragraph used to claim that, and it was not true. Until #614, one Tab from the field left edit mode and unmounted both buttons before focus could reach them; Enter on Cancel confirmed; Space on either did nothing. See "Combining showActions and confirmOnBlur" for the measurements and the three causes. Behaviour is pinned by packages/tests/e2e/inline-edit-keyboard-actions.spec.ts.

  • Live region — the error message is wrapped in a role="alert" element, which screen readers announce immediately without interrupting the current speech.
  • aria-busy — the root sets aria-busy="true" while an async validator is pending. This pauses incremental announcements on some readers.
  • Focus management — on edit entry, the input is focused automatically (autoFocus=true) and its content is selected (selectOnFocus=true). On confirm / cancel the component moves focus back to the display affordance explicitly: leaving edit mode unmounts whichever element held the focus, and without that move document.activeElement falls back to <body> (measured), so the keyboard caret is lost and Tab restarts from the top of the document. The focus is not recalled when the user left on their own — a Tab out of the component commits and lets focus continue to the next control.
  • Custom slots — when you supply #display or #edit, you take ownership of the ARIA contract. Pass an aria-label on the trigger and forward aria-invalid / aria-describedby to the input.

useInlineEdit composable ​

For headless consumers (custom widgets, data-grid cells, …) use the composable directly:

ts
import { ref } from 'vue'
import { useInlineEdit } from '@origam/composables'

const model = ref('hello')
const {
    isEditing, draft, error, isPending,
    edit, confirm, cancel, setValue
} = useInlineEdit(model, {
    validate: (v) => v.length >= 3 || 'Min 3 chars',
    trim: true,
    onConfirm: (v) => (model.value = v),
})

The composable deliberately does NOT call useLocale() — it stays usable without createOrigam(). The single user-facing string it can produce (when a validator rejects without returning its own message) is therefore exposed as the invalidMessage option, which <OrigamInlineEdit> fills with t('origam.inline_edit.invalid_value'):

OptionTypeDefaultNotes
rulesArray<TInlineEditRule>undefinedEvaluated first, stops at the first failure.
validateTInlineEditValidatorundefinedRuns only if every rule passes.
trimbooleantrueApplied before validating AND before emitting.
invalidMessagestring'Invalid value'Used when a validator rejects without its own message.
onConfirm / onCancel / onErrorcallbacksundefinedThe SFC wires these to its emits.
ReturnTypeNotes
isEditingRef<boolean>True while in edit mode.
draftRef<string>Live draft value. Mutate via setValue.
errorRef<string | null>Last validation error message.
isPendingRef<boolean>True while an async validator is in flight.
edit() => voidSnapshot the model into the draft and switch to edit mode.
confirm() => Promise<boolean>Run the validator and (if it passes) commit. Resolves true on success.
cancel() => voidDiscard the draft and revert.
setValue(next: string) => voidProgrammatic draft update — also clears any stale error.

Stale Promise verdicts are automatically discarded: if the user cancels (or fires another confirm) while a validator is still in flight, the late resolution is ignored — no double-commit, no race.

  • OrigamTextField — the full-fledged single-line form field. Use it when you need labels, prepend / append slots, prefixes, validation rules from a Form, … OrigamInlineEdit uses it internally in single-line edit mode.
  • OrigamTextareaField — multi-line variant. Used internally by OrigamInlineEdit in multiline=true edit mode.
  • OrigamClipboard — same "lightweight affordance" philosophy applied to copy-to-clipboard.