Skip to content
Kappa
Editable
@dicehub/kappav0.4.2

Editable

Lets users edit a short value in place without leaving its current context.

<script setup lang="ts">
import { Editable } from "@dicehub/kappa/components/editable";
</script>

<template>
  <Editable.Root
    id="project-name-editor"
    default-value="Ocean current study"
    activation-mode="click"
  >
    <Editable.Label>Project name</Editable.Label>
    <Editable.Area>
      <Editable.Input aria-label="Project name" />
      <Editable.Preview />
    </Editable.Area>
    <Editable.Control>
      <Editable.EditTrigger aria-label="Edit">Edit</Editable.EditTrigger>
      <Editable.SubmitTrigger aria-label="Save">Save</Editable.SubmitTrigger>
      <Editable.CancelTrigger aria-label="Cancel">Cancel</Editable.CancelTrigger>
    </Editable.Control>
  </Editable.Root>
</template>

Installation

Editable is part of the main Kappa package. Ark UI supplies edit state, keyboard behavior, focus management, form integration, and accessible relationships.

Barrel

import { Editable } from "@dicehub/kappa";

Granular

import { Editable } from "@dicehub/kappa/components/editable";

Usage

Place Input and Preview in the same Area. The two parts keep one stable footprint while edit mode changes. Single-line inputs use a compact line height so the text selection does not fill the control height. Use a visible Label when the value needs context.

<script setup lang="ts">
import { Editable } from "@dicehub/kappa/components/editable";
</script>

<template>
  <Editable.Root
    id="section-name-editor"
    default-value="Boundary conditions"
    activation-mode="click"
  >
    <Editable.Label>Section name</Editable.Label>
    <Editable.Area>
      <Editable.Input aria-label="Section name" />
      <Editable.Preview />
    </Editable.Area>
  </Editable.Root>
</template>

Composition

Typical part hierarchy
Editable.Root
├── Editable.Label
├── Editable.Area
│   ├── Editable.Input
│   └── Editable.Preview
└── Editable.Control
    ├── Editable.EditTrigger
    ├── Editable.SubmitTrigger
    └── Editable.CancelTrigger

The compound API follows Ark UI part names. Root also works as Editable. Named parts and hooks remain available for granular imports and external state machines.

<Editable.Root default-value="Project Delta">
  <Editable.Label>Project name</Editable.Label>
  <Editable.Area>
    <Editable.Input aria-label="Project name" />
    <Editable.Preview />
  </Editable.Area>
  <Editable.Control>
    <Editable.EditTrigger aria-label="Edit">Edit</Editable.EditTrigger>
    <Editable.SubmitTrigger aria-label="Save">Save</Editable.SubmitTrigger>
    <Editable.CancelTrigger aria-label="Cancel">Cancel</Editable.CancelTrigger>
  </Editable.Control>
</Editable.Root>

Examples

Explicit Controls

Set submitMode="none" when users must confirm or cancel with visible actions.

<script setup lang="ts">
import { Editable } from "@dicehub/kappa/components/editable";
</script>

<template>
  <Editable.Root
    id="task-name-editor"
    default-value="Mesh review"
    activation-mode="click"
    submit-mode="none"
  >
    <Editable.Label>Task name</Editable.Label>
    <Editable.Area>
      <Editable.Input aria-label="Task name" />
      <Editable.Preview />
    </Editable.Area>
    <Editable.Control>
      <Editable.EditTrigger aria-label="Edit">Edit</Editable.EditTrigger>
      <Editable.SubmitTrigger aria-label="Save">Save</Editable.SubmitTrigger>
      <Editable.CancelTrigger aria-label="Cancel">Cancel</Editable.CancelTrigger>
    </Editable.Control>
  </Editable.Root>
</template>

Controlled

Use v-model for the live value. Use valueCommit when application work must start only after the user commits the edit.

<script setup lang="ts">
import { ref } from "vue";
import { Editable } from "@dicehub/kappa/components/editable";

const projectName = ref("Ocean current study");
const committedName = ref(projectName.value);
</script>

<template>
  <Editable.Root
    id="controlled-project-name-editor"
    v-model="projectName"
    activation-mode="click"
    @value-commit="committedName = $event.value"
  >
    <Editable.Label>Project name</Editable.Label>
    <Editable.Area>
      <Editable.Input aria-label="Project name" />
      <Editable.Preview />
    </Editable.Area>
  </Editable.Root>
  <output aria-live="polite">Saved value: {{ committedName }}</output>
</template>

States

Disabled, read-only, and invalid states stay distinct in both color themes.

<script setup lang="ts">
import { Editable } from "@dicehub/kappa/components/editable";
</script>

<template>
  <Editable.Root id="disabled-project-editor" default-value="Archived project" disabled>
    <Editable.Label>Disabled</Editable.Label>
    <Editable.Area><Editable.Input aria-label="Disabled" /><Editable.Preview /></Editable.Area>
  </Editable.Root>

  <Editable.Root id="readonly-run-editor" default-value="Run 4189" read-only>
    <Editable.Label>Read only</Editable.Label>
    <Editable.Area><Editable.Input aria-label="Read only" /><Editable.Preview /></Editable.Area>
  </Editable.Root>

  <Editable.Root
    id="invalid-project-editor"
    default-value="Untitled"
    invalid
    activation-mode="click"
  >
    <Editable.Label>Invalid</Editable.Label>
    <Editable.Area><Editable.Input aria-label="Invalid" /><Editable.Preview /></Editable.Area>
  </Editable.Root>
</template>

Sizes

Use size="xs" on Root or RootProvider for dense dicehub settings. At a 16px root font size, it matches the dicehub input field's 20px height, 3px side padding, and 2px corners. Kappa keeps its typeface, 13px text, and flexible field width. The other heights are 28px for sm, 36px for default, and 40px for lg. Input and Preview keep the same height while editing.

<script setup lang="ts">
import { Editable, EDITABLE_SIZES } from "@dicehub/kappa/components/editable";
</script>

<template>
  <Editable.Root
    v-for="size in EDITABLE_SIZES"
    :id="`size-${size}-editor`"
    :key="size"
    :size="size"
    default-value="Surface refinement"
    activation-mode="click"
  >
    <Editable.Label>{{ size }}</Editable.Label>
    <Editable.Area>
      <Editable.Input :aria-label="`${size} editable field`" />
      <Editable.Preview />
    </Editable.Area>
  </Editable.Root>
</template>

Textarea

Use Input with as-child to merge Ark UI behavior into one textarea. Enter creates a new line; Ctrl+Enter, or Command+Enter on macOS, submits when enabled.

<script setup lang="ts">
import { Editable } from "@dicehub/kappa/components/editable";
</script>

<template>
  <Editable.Root
    id="review-note-editor"
    default-value="Review the inlet values before the next solver run."
    activation-mode="click"
    submit-mode="none"
  >
    <Editable.Label>Review note</Editable.Label>
    <Editable.Area>
      <Editable.Input as-child aria-label="Review note">
        <textarea rows="3" />
      </Editable.Input>
      <Editable.Preview />
    </Editable.Area>
    <Editable.Control>
      <Editable.EditTrigger aria-label="Edit">Edit</Editable.EditTrigger>
      <Editable.SubmitTrigger aria-label="Save">Save</Editable.SubmitTrigger>
      <Editable.CancelTrigger aria-label="Cancel">Cancel</Editable.CancelTrigger>
    </Editable.Control>
  </Editable.Root>
</template>

Accessibility

  • Label is associated with the input through Ark UI-managed identifiers.
  • Enter commits a single-line edit when the selected submit mode allows it.
  • Escape cancels an edit and restores the value present when editing started.
  • Focus, double-click, click, or an explicit trigger can enter edit mode.
  • Visible focus and invalid states use Kappa semantic tokens.

See theofficial Ark UI Editable documentationfor the primitive behavior contract.

API Reference

Editable.Root

PropTypeDefaultDescription
modelValuestring—Controlled text value. Use v-model for two-way binding.
defaultValuestring""Initial text value for uncontrolled use.
editbooleanfalseControlled edit mode. Use v-model:edit for two-way binding.
defaultEditbooleanfalseStarts an uncontrolled instance in edit mode.
activationMode"focus" | "click" | "dblclick" | "none""focus"Interaction that enters edit mode.
submitMode"enter" | "blur" | "both" | "none""both"Interaction that commits a value.
autoResizebooleanfalseSizes the input from its content.
disabledbooleanfalsePrevents editing and focus interaction.
readOnlybooleanfalseKeeps the value focusable without allowing edits.
invalidbooleanfalseMarks the current value as invalid.
requiredbooleanfalseMarks the underlying form input as required.
maxLengthnumber—Limits the editable value length.
namestring—Name used for form submission.
placeholderstring | { edit; preview }—Placeholder for empty preview and input states.
selectOnFocusbooleantrueSelects input text when edit mode starts.
size"xs" | "sm" | "default" | "lg""default"Field height at a 16px root font size: xs 20px, sm 28px, default 36px, lg 40px. Available on Root and RootProvider.

Parts

PartElementDescription
Editable.RootdivOwns inline-edit state and form integration.
Editable.LabellabelLabels the editable input.
Editable.AreadivAligns the preview and input in one stable area.
Editable.PreviewspanShows the committed value outside edit mode.
Editable.InputinputEdits the current value. Use as-child for a textarea.
Editable.ControldivGroups edit, submit, and cancel actions.
Editable.EditTriggerbuttonEnters edit mode.
Editable.SubmitTriggerbuttonCommits the current value.
Editable.CancelTriggerbuttonRestores the value present when editing started.
Editable.ContextrenderlessExposes the reactive Ark UI API to a slot.
Editable.RootProviderdivProvides an external useEditable state machine.

Events

EventPayloadDescription
update:modelValuestringEmitted as the input value changes.
update:editbooleanEmitted when edit mode changes.
valueChangeEditableValueChangeDetailsReports each value change.
valueCommitEditableValueChangeDetailsReports a committed value.
valueRevertEditableValueChangeDetailsReports a canceled edit.
editChangeEditableEditChangeDetailsReports edit-mode transitions.

Exports

ExportDescription
EditableCompound component and root alias.
EditableRoot and named partsUnaugmented component exports.
useEditableCreates an external Ark UI state machine.
useEditableContextReads the nearest Editable context.
EditableProps and part typesPublic TypeScript contracts.