Theme
Version
GitHub PyPI Discord
On this page

Editable

Use CEditable for compact names, titles, and labels that are usually read and occasionally changed. It keeps one native Input as form and validity truth.

Editable at a glance

Editable at a glance
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class EditableAtAGlance(Component):
    template = """
      <c-CField>
        <c-fill name="label">Project name</c-fill>
        <c-fill name="description">Use the pencil to rename this project in place.</c-fill>
        <c-fill name="default">
          <c-CEditable value="Aurora atlas" name="project-name" />
        </c-fill>
      </c-CField>
    """


preview = EditableAtAGlance()
preview  # noqa: B018

Submit and reset a value

Use Editable in a form
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class EditableForm(Component):
    template = """
      <form x-data @submit.prevent="result = Object.fromEntries(new FormData($event.target))">
        <c-CField required>
          <c-fill name="label">Workspace title</c-fill>
          <c-fill name="default">
            <c-CEditable value="Field notes" name="title" />
          </c-fill>
        </c-CField>
        <c-CButton type="submit">Save form</c-CButton>
        <c-CButton type="reset" variant="ghost">Reset</c-CButton>
        <output x-text="JSON.stringify(result)"></output>
      </form>
    """


preview = EditableForm()
preview  # noqa: B018

Control the committed value

Control Editable
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class ControlledEditable(Component):
    template = """
      <div x-data>
        <c-CEditable
          value="Atlas"
          $c-props="{
            value:$store.editableExample.value,
            onValueChange:(next) => $store.editableExample.value = next,
          }"
        />
        <p>Committed: <strong x-text="$store.editableExample.value"></strong></p>
      </div>
    """
    js = "Alpine.store('editableExample', {value:'Atlas'});"


preview = ControlledEditable()
preview  # noqa: B018

Choose when editing commits

The default both mode commits with Enter or when focus leaves the whole component. enter, blur, and explicit narrow that behavior.

Editable submit modes
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class EditableSubmitModes(Component):
    template = """
      <c-CStack>
        <c-CEditable value="Enter or blur" submit_mode="both" c-input_attrs="{'aria-label':'Both'}" />
        <c-CEditable value="Enter only" submit_mode="enter" c-input_attrs="{'aria-label':'Enter only'}" />
        <c-CEditable value="Blur only" submit_mode="blur" c-input_attrs="{'aria-label':'Blur only'}" />
        <c-CEditable value="Buttons only" submit_mode="explicit" c-input_attrs="{'aria-label':'Explicit'}" />
      </c-CStack>
    """


preview = EditableSubmitModes()
preview  # noqa: B018

Place edit actions

Pencil, confirm, and cancel actions sit inside the Input at inline-end by default. Use action_position="outside" when they need independent space.

Place Editable actions
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class EditableActionPositions(Component):
    template = """
      <c-CStack>
        <c-CEditable value="Actions inside by default" editing c-input_attrs="{'aria-label':'Inside actions'}" />
        <c-CEditable
          value="Actions beside the input" editing action_position="outside"
          c-input_attrs="{'aria-label':'Outside actions'}"
        />
      </c-CStack>
    """


preview = EditableActionPositions()
preview  # noqa: B018

States, variants, and sizes

Editable states
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class EditableStates(Component):
    template = """
      <c-CStack>
        <c-CEditable value="Available" c-input_attrs="{'aria-label':'Available title'}" />
        <c-CEditable value="Read only" readonly c-input_attrs="{'aria-label':'Read-only title'}" />
        <c-CEditable value="Disabled" disabled c-input_attrs="{'aria-label':'Disabled title'}" />
        <c-CEditable value="Needs review" invalid c-input_attrs="{'aria-label':'Invalid title'}" />
        <c-CEditable placeholder="Empty value" c-input_attrs="{'aria-label':'Empty title'}" />
      </c-CStack>
    """


preview = EditableStates()
preview  # noqa: B018
Editable variants and sizes
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class EditableVariants(Component):
    template = """
      <c-CStack>
        <c-CEditable value="Small outline" variant="outline" size="sm" />
        <c-CEditable value="Medium filled" variant="filled" />
        <c-CEditable value="Large plain" variant="plain" size="lg" />
      </c-CStack>
    """


preview = EditableVariants()
preview  # noqa: B018

Keyboard behavior

The edit Button enters edit mode. Enter commits when enabled by submit_mode, Escape cancels, and Tab follows ordinary page order. Blur modes commit only after focus leaves the Input and both edit actions.

Edit with the keyboard
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class EditableKeyboard(Component):
    template = """
      <c-CStack>
        <p>Tab to Edit, press Enter to edit, then Enter to save or Escape to cancel.</p>
        <c-CEditable value="Keyboard friendly" />
        <c-CButton variant="outline">Next focus target</c-CButton>
      </c-CStack>
    """


preview = EditableKeyboard()
preview  # noqa: B018

Customize Editable

Customize Editable
Show code
import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class CustomizedEditable(Component):
    template = """
      <c-CEditable
        value="Branded title" editing
        style="--cui-editable-background:#fff8eb; --cui-editable-border-color:#f79009;
               --cui-editable-focus-color:#b54708; --cui-editable-radius:1rem"
        c-input_attrs="{'aria-label':'Branded title'}"
      />
    """


preview = CustomizedEditable()
preview  # noqa: B018

Accessibility and forms

View mode exposes ordinary text and a named edit Button. Edit mode exposes one native text Input plus named confirm and cancel Buttons. The Input stays the successful form control in both modes and owns required validity and reset. Before client initialization the native Input is the visible fallback.

Use CInput for a value that is primarily edited, and CTextarea for multiline content.

API reference

Inputs

CEditable server inputs

Server inputs are passed in a template through <c-CEditable ... /> or in Python through CEditable(...).

InputTypeDefaultEffect
valuestr""Sets the initial committed and native form value.
placeholderstr"Click to edit"Supplies author-localized empty preview and Input text.
namestr | NoneNoneSets the native form field name.
formstr | NoneNoneAssociates the native Input with a Form ID.
idstr | NoneNoneSets native Input identity.
editingboolFalseSets initial edit mode.
requiredbool | NoneNoneEnables native required validity outside Field.
disabledbool | NoneNoneDisables editing and form contribution.
readonlybool | NoneNonePreserves submission while preventing editing.
invalidbool | NoneNoneAdds owner-supplied invalid presentation.
max_lengthint | NoneNoneSets native maximum length.
autocompletestr | NoneNoneSets the native autocomplete hint.
inputmodestr | NoneNoneSets the native virtual-keyboard hint.
submit_mode"enter" | "blur" | "both" | "explicit" (CEditableSubmitMode)"both"Selects commit triggers.
select_on_focusboolTrueSelects the draft when editing begins.
action_position"inside" | "outside" (CEditableActionPosition)"inside"Places edit actions inside the Input at inline-end or outside it.
edit_labelstr"Edit"Names the pencil Button.
submit_labelstr"Save"Names the confirm Button.
cancel_labelstr"Cancel"Names the cancel Button.
variant"outline" | "filled" | "plain" (CEditableVariant)"outline"Selects surface treatment.
size"sm" | "md" | "lg" (CEditableSize)"md"Selects Input and action geometry.
class_CClassValue | NoneNoneAdds root classes.
styleCStyleValue | NoneNoneAdds root inline styles.
attrsMapping[str, object] | NoneNoneAdds trusted nonconflicting root attributes.
input_attrsMapping[str, object] | NoneNoneAdds trusted native Input attributes and relationships.
preview_attrsMapping[str, object] | NoneNoneAdds trusted nonconflicting preview attributes.

CEditable client inputs

Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CEditable />.

InputTypeOmitted behaviorEffect
valuestring | nullReleases control to the committed value.Controls the committed value while supplied.
editingboolean | nullReleases control to committed edit mode.Controls view or edit mode while supplied.
requiredboolUses the server or Field fallback.Reactively changes required validity.
disabledboolUses the server or Field fallback.Reactively disables editing.
readonlyboolUses the server or Field fallback.Reactively prevents editing while preserving submission.
invalidboolUses the server or Field fallback.Reactively changes invalid presentation.
submitModeCEditableSubmitModeUses the server value.Reactively changes commit triggers.
selectOnFocusboolUses the server value.Reactively changes entry selection.
actionPositionCEditableActionPositionUses the server value.Reactively places the actions inside or outside.
variantCEditableVariantUses the server value.Reactively changes treatment.
sizeCEditableSizeUses the server value.Reactively changes geometry.
onValueChange((value: string, detail: CEditableValueChangeDetail) => void) | undefinedNo component callback runs.Receives commit and reset requests.
onEditChange((editing: boolean, detail: CEditableEditChangeDetail) => void) | undefinedNo component callback runs.Receives mode requests and forced closes.

Slots

-

Events

Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.

CEditable events

EventSignatureTrigger and timingDetailControlled and cancellation behavior
onValueChange(value: string, detail: CEditableValueChangeDetail) => void (CEditableValueChangeDetail)Submit blur or reset request.{value, previousValue, controlled, source, sourceEvent} (CEditableValueChangeDetail)Commits immediately when uncontrolled and waits for owner acceptance when controlled.
onEditChange(editing: boolean, detail: CEditableEditChangeDetail) => void (CEditableEditChangeDetail)Edit submit cancel blur reset or safety transition.{editing, reason, controlled, forced, source} (CEditableEditChangeDetail)Controlled requests notify without changing mode; forced safety transitions always close.

Methods

-

CSS

CSS variables to theme the components. Set them on an ancestor or the component itself.

CEditable CSS variables

Apply these variables to CEditable or one of its ancestors.

VariableTypePurposeDefault
--cui-editable-backgroundcolorPreview and Input surface.Canvas
--cui-editable-foregroundcolorPrimary text.CanvasText
--cui-editable-border-colorcolorSurface border.scheme-aware border
--cui-editable-hover-border-colorcolorHover border.scheme-aware strong border
--cui-editable-focus-colorcolorFocus outline.Highlight
--cui-editable-invalid-border-colorcolorInvalid border.scheme-aware red
--cui-editable-muted-colorcolorEmpty preview foreground.scheme-aware muted
--cui-editable-action-backgroundcolorAction Button surface.CanvasText mix
--cui-editable-action-foregroundcolorAction Button foreground.CanvasText
--cui-editable-radiuslengthSurface corners.0.5rem
--cui-editable-heightlengthMinimum surface height.size-derived
--cui-editable-paddinglengthSurface padding.size-derived
--cui-editable-action-sizelengthAction Button square size.size-derived
--cui-editable-gaplengthAction and outside-layout gap.0.375rem

Attributes

HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.

CEditable attributes

AttributeElementTypeMeaning
data-editingRootpresent-or-absentMirrors effective edit mode.
data-emptyRootpresent-or-absentMirrors an empty committed value.
data-requiredRootpresent-or-absentMirrors required validity.
data-disabledRootpresent-or-absentMirrors effective disabled state.
data-readonlyRootpresent-or-absentMirrors read-only state.
data-invalidRootpresent-or-absentMirrors external or native invalid state.
data-submit-modeRootCEditableSubmitModeReflects commit behavior.
data-action-positionRootCEditableActionPositionReflects action placement.
data-variantRootCEditableVariantReflects treatment.
data-sizeRootCEditableSizeReflects geometry.
aria-invalidNative Inputtrue or absentMirrors external or native invalid state.
aria-describedbyNative InputIDREF list or absentMerges Field and trusted description relationships.
aria-errormessageNative InputIDREF list or absentMerges active Field and trusted error relationships.

Selectors

Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.

CEditable selectors

SelectorElementPurpose
[data-citry-ui-part="root"]Root divStable root and state surface.
[data-citry-ui-part="preview"]Preview divView-mode surface.
[data-citry-ui-part="preview-value"]Preview spanCommitted or placeholder text.
[data-citry-ui-part="edit-action"]ButtonEnters edit mode.
[data-citry-ui-part="edit-surface"]DivInput and edit action layout.
[data-citry-ui-part="input"]Native InputDraft focus form and validity owner.
[data-citry-ui-part="actions"]SpanConfirm and cancel layout.
[data-citry-ui-part="submit-action"]ButtonCommits the draft.
[data-citry-ui-part="cancel-action"]ButtonDiscards the draft.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

InterfaceDefinition
CEditableActionPositionLiteral["inside", "outside"]
CEditableSubmitModeLiteral["enter", "blur", "both", "explicit"]
CEditableVariantLiteral["outline", "filled", "plain"]
CEditableSizeLiteral["sm", "md", "lg"]
CEditableValueSourceLiteral["submit", "blur", "reset"]
CEditableEditReasonLiteral["edit", "submit", "cancel", "blur", "reset", "disabled", "readonly", "invalid"]

CEditableValueChangeDetail

FieldTypeDefaultMeaning
valuestring-Requested value.
previousValuestring-Previous committed value.
controlledbool-Whether client value owns the channel.
sourceCEditableValueSource-Commit source.
sourceEventEvent | None-Native source event when present.

CEditableEditChangeDetail

FieldTypeDefaultMeaning
editingbool-Requested or forced mode.
reasonCEditableEditReason-Mode reason.
controlledbool-Whether client editing owns the channel.
forcedbool-Whether safety made closure nonrejectable.
sourceEventTarget | None-Native source or safety owner.

Translation keys

Catalog keys used by this family. An explicit component input or slot listed in Override takes precedence over the catalog for that instance.

CEditable translation keys

KeyPurposeVariablesOverrideBrowser updates
citry-ui-editable-click-to-editSupplies empty preview text and the editor placeholder.Noneplaceholder inputi18n.bind() updates every stateful destination.
citry-ui-editable-editNames the edit control.Noneedit_label input$c-tr updates aria-label.
citry-ui-editable-saveNames the save control.Nonesubmit_label input$c-tr updates aria-label.
citry-ui-editable-cancelNames the cancel control.Nonecancel_label input$c-tr updates aria-label.