Appearance
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.
| Prop | Type | Values | Effect |
|---|---|---|---|
fontSize | TFontSize | xs · 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) |
fontWeight | TFontWeight | regular · medium · semibold · bold · extrabold · black | --origam-inline-edit__error---font-weight (error message only — action-btn weight is hardcoded 600) |
Props
| Prop | Type | Default | Notes |
|---|---|---|---|
modelValue | string | number | required | v-model target. Numbers round-trip as numbers. |
placeholder | string | origam.inline_edit.placeholder | Shown on the input and on the empty display. Unset, it resolves through the DS locale ("Click to edit" in English). |
rules | Array<(v: string) => true | string | Promise<…>> | undefined | Array 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<…> | undefined | Sync or async validator. Returning a string surfaces it as an error and keeps the editor open. Only runs if all rules pass. |
autoFocus | boolean | true | Auto-focus the input on edit entry. |
selectOnFocus | boolean | true | Select all text after auto-focus. |
confirmOnBlur | boolean | true | Commit 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". |
confirmOnEnter | boolean | true | Confirm on Enter. In multiline mode, this becomes Cmd/Ctrl+Enter. |
cancelOnEscape | boolean | true | Revert on Escape. |
disabled | boolean | false | Display becomes non-interactive; edit() short-circuits. |
multiline | boolean | false | Render a <textarea> instead of <input>. |
trim | boolean | true | Strip surrounding whitespace before validate + emit. |
inputType | 'text' | 'number' | 'email' | 'tel' | 'text' | Native HTML input type in single-line mode. |
loadingOnConfirm | boolean | false | Adds a CSS hook (.origam-inline-edit--loading-on-confirm) while a Promise validator is in flight. aria-busy is set regardless. |
showActions | boolean | false | Render built-in Edit / Confirm / Cancel buttons. See "Action buttons" section below. |
tag | string | 'div' (was 'span' before 2026-09) | Root element tag. See "Migration — tag default changed" below if you relied on the old default. |
id | string | undefined | Forwarded to the root element. |
class | string | Array | object | undefined | Merged onto the root element alongside the state classes. |
style | string | Array | object | undefined | Merged 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.
| Key | English |
|---|---|
origam.inline_edit.placeholder | Click to edit |
origam.inline_edit.edit_aria_label | Edit {0} — display affordance |
origam.inline_edit.edit | Edit — the pencil action button |
origam.inline_edit.confirm | Confirm |
origam.inline_edit.cancel | Cancel |
origam.inline_edit.field_aria_label | Edit value — accessible name of the input |
origam.inline_edit.invalid_value | Invalid 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
| Emit | Payload | When |
|---|---|---|
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
| Mode | Buttons visible | Button hidden |
|---|---|---|
| Display | Edit (✎) next to the display label | Confirm, Cancel |
| Edit | Confirm (✓), Cancel (✕) inside the field | Edit |
- 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 —showActionsis purely additive. - When
disabledistrue, 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">✓</button>
<button data-cy="origam-inline-edit-action-cancel">✕</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 affordanceMouse 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:
Enteron Cancel used to confirm: the button'skeydownbubbled into the field's ownEntershortcut (measured — the draft was committed instead of discarded). Field shortcuts now only act on events coming from the input itself.Spaceon either button did nothing: the field'sappendInnerzone calledpreventDefault()onEnter/Spacebubbling 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:
rulesare evaluated first, sequentially. The first failing rule stops evaluation and surfaces its message.validateis 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 anaria-labelof"Edit {value or placeholder}". Keyboard users get focus / Enter / Space semantics for free. - Edit affordance — the native
<input>/<textarea>carries anaria-label(origam.inline_edit.field_aria_label) so it always has an accessible name. It is additionally decorated witharia-invalidandaria-describedby(pointing to the inline error) when a validator fails. Before this was wired, the only naming source was theplaceholder— the last-resort branch of the accessible-name algorithm, which yields no name at all underplaceholder="". - Action buttons — with
showActions, the display affordance and the pencil button both enter edit mode. The pencil carriestabindex="-1"andaria-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}andEdit) as a net for a consumer who stripsaria-hidden. Confirm and Cancel are keyboard reachable —Tabfrom the field lands on Confirm, then Cancel — and actionable with bothEnterandSpace.⚠️ This paragraph used to claim that, and it was not true. Until #614, one
Tabfrom the field left edit mode and unmounted both buttons before focus could reach them;Enteron Cancel confirmed;Spaceon either did nothing. See "CombiningshowActionsandconfirmOnBlur" for the measurements and the three causes. Behaviour is pinned bypackages/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 setsaria-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 movedocument.activeElementfalls back to<body>(measured), so the keyboard caret is lost andTabrestarts from the top of the document. The focus is not recalled when the user left on their own — aTabout of the component commits and lets focus continue to the next control. - Custom slots — when you supply
#displayor#edit, you take ownership of the ARIA contract. Pass anaria-labelon the trigger and forwardaria-invalid/aria-describedbyto 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'):
| Option | Type | Default | Notes |
|---|---|---|---|
rules | Array<TInlineEditRule> | undefined | Evaluated first, stops at the first failure. |
validate | TInlineEditValidator | undefined | Runs only if every rule passes. |
trim | boolean | true | Applied before validating AND before emitting. |
invalidMessage | string | 'Invalid value' | Used when a validator rejects without its own message. |
onConfirm / onCancel / onError | callbacks | undefined | The SFC wires these to its emits. |
| Return | Type | Notes |
|---|---|---|
isEditing | Ref<boolean> | True while in edit mode. |
draft | Ref<string> | Live draft value. Mutate via setValue. |
error | Ref<string | null> | Last validation error message. |
isPending | Ref<boolean> | True while an async validator is in flight. |
edit | () => void | Snapshot 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 | () => void | Discard the draft and revert. |
setValue | (next: string) => void | Programmatic 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.
Related
OrigamTextField— the full-fledged single-line form field. Use it when you need labels, prepend / append slots, prefixes, validation rules from a Form, …OrigamInlineEdituses it internally in single-line edit mode.OrigamTextareaField— multi-line variant. Used internally byOrigamInlineEditinmultiline=trueedit mode.OrigamClipboard— same "lightweight affordance" philosophy applied to copy-to-clipboard.