Appearance
OrigamField
<OrigamField> is the visual shell shared by all text-based inputs (TextField, NumberField, PasswordField, etc.). It handles the floating label, outline/filled variant, prefix/suffix, inner prepend/append icons, loader, and the density calculation.
OrigamField is rarely used directly — prefer the typed atoms. Use it when you need to embed a custom <input> or non-standard control inside the standard field chrome.
Basic usage
vue
<template>
<OrigamField label="Custom input">
<template #default="{ id, onFocus, onBlur, ref: inputRef }">
<input :id="id" :ref="inputRef" @focus="onFocus" @blur="onBlur" />
</template>
</OrigamField>
</template>Variants
vue
<template>
<OrigamField variant="outlined" label="Outlined" />
<OrigamField variant="filled" label="Filled" />
<OrigamField variant="plain" label="Plain" />
</template>Color
vue
<template>
<OrigamField color="primary" label="Primary" />
<OrigamField color="secondary" label="Secondary" />
</template>Density
vue
<template>
<OrigamField density="compact" label="Compact" />
<OrigamField density="default" label="Default" />
<OrigamField density="comfortable" label="Comfortable" />
</template>Rounded
The field corner radius defaults to the active theme's --origam-field---border-radius token (e.g. 6px sobre, 8px apple, 10px glass, 12px material, 0px editorial). Pass the rounded prop (inherited from IRoundedProps) to override it per instance — named rungs (xs/sm/md/lg/xl), the legacy boolean, or a free-form CSS value.
vue
<template>
<OrigamField label="Themed default" />
<OrigamField label="Medium" rounded="md" />
<OrigamField label="Custom" rounded="10px" />
<OrigamField label="Pill" rounded="9999px" />
</template>The inline padding automatically clears the corner: when the radius is larger than --origam-field---padding-start / -end (e.g. rounded="lg" against an 8px padding), the field floors its inline padding at the radius so the value text and the floating label never collide with the rounded outline. The floor is capped at the control height, so an intentional pill (rounded="9999px") stays laid out instead of inheriting a 9999px padding.
That floor is themable: a theme (or any ancestor) that sets --origam-field---corner-clearance replaces the computed value, e.g. a pill field whose text should start at 20px instead of at its own height.
| Token | Default | Role |
|---|---|---|
--origam-field---corner-clearance | per instance: min(radius, control height) | Floor of the inline padding. 0px disables it. |
Prefix / suffix
vue
<template>
<OrigamField label="Price" prefix="$" suffix=".00" />
</template>Prepend / append inner
vue
<template>
<OrigamField label="Search" prepend-inner-icon="mdi-magnify" />
</template>Accessible name when the inner zone is clickable (#747)
@click:prependInner / @click:appendInner make the zone actionable. It only becomes a real control — role="button", tab stop, announced — when you also give it a name, because its content is an icon or an avatar and carries no text.
| Prop | Type | Description |
|---|---|---|
prependInnerAriaLabel | string | Accessible name of the inner prepend zone. i18n key or literal string. |
appendInnerAriaLabel | string | Accessible name of the inner append zone. Same contract. |
vue
<template>
<OrigamField
label="Search"
prepend-inner-icon="mdi-magnify"
prepend-inner-aria-label="Run the search"
@click:prepend-inner="search"
/>
</template>⛔ Without the label, no role and no tabindex are emitted, and a dev-time warning names the prop to add — the DS declines to announce a control it cannot name (WCAG 2.1 4.1.2). The click emit is untouched. Inherited by the whole field family: TextField, TextareaField, PasswordField, NumberField, OtpInputField, DatePickerField, ColorPickerField, FileField.
States (dirty / focused / error / disabled)
vue
<template>
<OrigamField label="Error" :error="true" />
<OrigamField label="Disabled" disabled />
<OrigamField label="Dirty" :dirty="true" />
</template>Loading
loading is true, a number (0..100) or { type: 'line' | 'circular', … } (default line: a strip along the bottom edge). The <input> and the label stay mounted - focus, caret and typed text survive a validation or save in flight. { type: 'skeleton' } is refused at compile time (TControlLoadingValue); the same holds for OrigamSelect, OrigamTextField and OrigamTextareaField, which inherit it.
Required
required renders an asterisk (<sup>*</sup>) on the nested <OrigamLabel> and exposes aria-required="true" through the default-slot props consumed by every field-family component (TextField, NumberField, PasswordField, FileField) on their real <input>.
vue
<template>
<OrigamField label="Email" required />
</template>Props — Typography (label surface)
fontSize sets --origam-field__label---font-size on the .origam-field__label element directly, which the SCSS reads for the floating label text size and the JS animation scale.
fontWeight, lineHeight and letterSpacing reach the SAME label element by a different path: <OrigamField> forwards its own props to the nested <OrigamLabel> (origamLabelRef.value.filterProps(props, …)), and OrigamLabel paints those three itself via its own --origam-label---* variables. Field's OWN --origam-field__label---* var for these three is written but unread — the visible effect comes from OrigamLabel's prefix, not Field's. See issue #501.
| Prop | Type | Default | Description |
|---|---|---|---|
fontSize | TFontSize | — | Font-size token (xs · sm · md · lg · xl · 2xl · …). Sets --origam-field__label---font-size. When unset the theme default applies. |
fontWeight | TFontWeight | — | Font-weight token, forwarded to the nested <OrigamLabel>. When unset the theme default applies. |
lineHeight | TLineHeight | — | Line-height token, forwarded to the nested <OrigamLabel>. When unset the theme default applies. |
letterSpacing | TLetterSpacing | — | Letter-spacing token, forwarded to the nested <OrigamLabel>. When unset the theme default applies. |
fontFamilywas removed fromIFieldProps(issue #501) — neither Field's own__labelprefix nor the forwardedOrigamLabelreads afont-familyvar.fontFamilyis a project-level setting configured once onOrigamApp.
Border (issue #726)
IFieldProps extends IBorderProps. The field does not paint a CSS border on its own box: it re-routes the width / style / colour useBorder resolves into the token channel its three outline legs already read — --origam-field---border-width, --origam-field__outline---border-style, --origam-field---border-color (plus --origam-field---border-opacity: 1, so an explicit colour is not washed out by the default .38).
That indirection is the whole point. The notch (__outline--notch) drops its top border to 0 under --active / --focused, which is what opens the gap the floating label sits in. A plain border: declaration on the box would paint a continuous line straight through that label — which is exactly what happened before #726, when border lived only on the outer <OrigamInput> wrapper (measured: label box [-7, 11], input border band [0, 2], 61.41 px² of label crossed; after the fix, 0 px²).
| Prop | Type | Default | Description |
|---|---|---|---|
border | boolean | number | string | TDirectionBoth | Array<…> | — | Outline width. true/'thin'/'thick', a number of px, or free-form CSS ('2px dashed red'). Feeds the notched outline, never a box border. |
borderColor | string | — | Outline colour. Sets --origam-field---border-color and forces --origam-field---border-opacity: 1. |
borderStyle | string | — | Outline line-style (solid · dashed · dotted · …). Sets --origam-field__outline---border-style. |
Directional values are not mapped.
border="top"and the per-side props (borderTop,borderBlock,borderLeftColor, …) have no meaning on a three-leg outline, so only the global width / style / colour are consumed; the legs keep the variant's own width for a directional value. Use thevariantprop (outlined·filled·underlined·plain) to choose which edges the field draws.
Slots
| Slot | Scope | Description |
|---|---|---|
default | { id, aria-describedby, isActive, isFocused, ref, onBlur, onFocus, class } | The control inside the field |
label | ILabelProps | Custom label content |
floatingLabel | ILabelProps | Custom floating label |
prefix | — | Before control |
suffix | — | After control |
prependInner | — | Inside before |
appendInner | — | Inside after |
loader | — | Loading indicator |
Emits
| Event | Payload | Description |
|---|---|---|
update:focused | boolean | Focus state changed |
update:active | boolean | Active (chrome) state changed — driven by useStateFlag(props, {state: 'active'}), toggles alongside focus/dirty/prefix/suffix |
click:clear | MouseEvent | Clear icon clicked |
click:prependInner | MouseEvent | Inner prepend clicked |
click:appendInner | MouseEvent | Inner append clicked |
focus / blur — use update:focused
⛔ @focus and @blur bound on <origam-field> never fire. They are not component emits (IFieldEmits does not declare them), and attribute fallthrough does not save them either: the field root is a plain <div> with no tabindex, so it is never focused itself, and focus / blur do not bubble (unlike focusin / focusout). Measured on the real component: a root-level onFocus / onBlur is called 0 times when the nested control takes and loses focus.
The working channel is @update:focused, wired by the onFocus / onBlur handlers the default slot hands to your control:
vue
<template>
<OrigamField label="Email" @update:focused="isFocused = $event">
<template #default="{ id, onFocus, onBlur }">
<input :id="id" class="origam-field__input" @focus="onFocus" @blur="onBlur">
</template>
</OrigamField>
</template>The same state is reflected on the root as origam-field--focused. If you genuinely need the raw DOM events at field level, listen for focusin / focusout, which do bubble.
Design tokens
| CSS variable | Default | Description |
|---|---|---|
--origam-field---border-radius | theme rung (fallback 8px) | Corner radius (overridable via rounded prop) |
--origam-field---border-color | semantic border | Outline color |
--origam-field---label-color | text-secondary | Label color |
--origam-field---placeholder-color | currentColor | Placeholder color of the inner input / textarea. |
--origam-field---placeholder-opacity | 0.5 | Placeholder opacity (also the focused value of the floating-label placeholder). |
--origam-field---bg-color | surface | Background |
--origam-field---density | 0px | Density offset |
--origam-field__input---padding-top | --origam-field__input---padding-block-md | Effective top padding of the input. Redirected onto a rung token by the size and variant rules below — override a rung, not this, when a rung applies. |
--origam-field__input---padding-block-sm · -md · -lg · -xl | 2px · 6px · 10px · 14px | Vertical padding rung selected by the size prop. |
--origam-field__input---padding-block-solo | 20px | Vertical padding rung used by variant="solo". |
--origam-field__input---padding-block-filled | 20px | Vertical padding rung used by variant="filled". |