OField

OField provides accessible label, description, feedback, state, and icon structure around a form control.

Usage

Step by step

1. Import OField from the ooko-ui/field public subpath and provide its visible label.
2. Read controlId, describedBy, and invalid from the default slot.
3. Apply those values to the slotted native control so its label, guidance, and error remain accessible.

Example

The rendered example and its source come from the same Vue single-file component.

Reference

Use the identifier shown on your invoice.

Interactive playground

Change the label, guidance, error, size, and field states. The preview updates immediately.

Example label

Helpful context appears here.

Size smmd Label Hint Error Disabled Read-only Required Hide label

Props

Prop	Type	Default	Description
size	OokoFormControlSize	"md"	Controls the field's form-control scale.
label	string	undefined	Visible or visually hidden accessible label.
controlId	string	undefined	Identifier assigned to the slotted control. A hydration-safe identifier is generated when omitted.
hint	string	undefined	Persistent guidance displayed below the control.
error	string	undefined	Validation error displayed below the control.
validation	readonly OokoValidationResult<unknown>[]	undefined	Validation results displayed below the control when no controlled error is present.
describedBy	string	undefined	Additional element identifiers merged into the control description.
hideLabel	boolean	false	Visually hides the label while preserving its accessible name.
required	boolean	false	Displays a decorative required marker.
disabled	boolean	false	Applies the disabled visual state to the field.
readonly	boolean	false	Applies the read-only visual state to the field.
icon	Component	undefined	Vue component rendered as a decorative control icon.
iconPosition	OFieldIconPosition	"leading"	Places the icon before or after the control.

Events

Event	Payload	Description
none	none	No custom Vue events are emitted.

Slots

Slot	Props	Description
default	OFieldDefaultSlotProps	Provides the native or custom form control.
icon	none	Provides custom decorative icon markup and overrides the icon prop.

Related types

Type	Definition
OFieldDefaultSlotProps	interface OFieldDefaultSlotProps { /** Identifier to assign to the slotted control. */ controlId: string; /** Identifier list to assign to the control's aria-describedby attribute. */ describedBy?: string; /** Whether the field currently exposes an error. */ invalid: boolean; }
OFieldIconPosition	type OFieldIconPosition = "leading" | "trailing";
OokoFormControlSize	type OokoFormControlSize = "sm" | "md";

CSS custom properties

Custom property	Default	Description
--o-field-gap	var(--o-space-1-5)	Sets the vertical space between field content.
--o-field-message-font-size	max(var(--o-font-size-xs), var(--o-font-size-min))	Sets the hint and error text size, never below the --o-font-size-min legibility floor by default.
--o-field-control-min-height	var(--o-control-form-height-md)	Sets the minimum control shell height.
--o-field-control-padding-inline	var(--o-space-3)	Sets the control shell inline padding.
--o-field-control-padding-block	var(--o-space-0)	Sets the control shell block padding.
--o-field-control-gap	var(--o-space-2)	Sets the space between an icon and control.
--o-field-control-border	1px solid var(--o-border-color-control)	Sets the control shell border while preserving state colors by default.
--o-field-control-background	var(--o-background-glass-strong)	Sets the control shell background of OInput, OTextarea, and OSelect, such as a translucent fill on a glass surface.
--o-field-control-border-radius	var(--o-radius-control)	Sets the control shell corner radius.
--o-field-focus-width	0.1875rem	Sets the focus outline width.
--o-field-focus-style	solid	Sets the focus outline style.
--o-field-focus-offset	0.125rem	Sets the distance between the shell and focus outline.
--o-field-disabled-opacity	0.5	Sets the opacity of the complete disabled field.
--o-field-icon-size	1.25rem	Sets the decorative icon size.
--o-field-icon-stroke-width	1.25	Sets the stroke width of line icons, such as Lucide's, inside the field.

Override example

:root {
  --o-field-control-border-radius: var(--o-radius-round);
  --o-field-icon-size: 1rem;
}

/* Translucent fields on a glass surface, for OInput, OTextarea, and OSelect. */
.glass-panel {
  --o-field-control-background: color-mix(in srgb, var(--o-background-color-default) 40%, transparent);
}

Accessibility

• The label uses the provided or generated control identifier, but the slotted control must bind controlId to its native id.
• The control must bind describedBy to aria-describedby and expose invalid through aria-invalid when applicable.
• The icon is decorative, hidden from assistive technologies, and must not contain interactive content.
• hideLabel preserves the label in the accessibility tree.
• Required, disabled, and read-only props provide presentation only; the consumer must apply the matching native or ARIA state to its slotted control.
• Validation messages are visible text in a polite live region. Error-level results expose the invalid state, and forced-colors mode receives explicit state borders.

Behavior and edge cases

• OField owns no value, validation rules, events, or form registration. It only presents supplied results; higher-level controls such as OInput and OTextarea run the rules.
• A controlled error takes presentation precedence over the validation result array.
• The icon slot overrides the icon prop. Icon position has no effect when neither is provided.
• Native input, select, and textarea elements placed directly in the default slot receive the standard Ooko control typography and reset.
• Consumer attributes and classes are forwarded to the field root.
• App defaults may configure size and iconPosition; direct props take precedence.