OInput

OInput renders a labelled single-line text input with accessible guidance and validation feedback.

Usage

Step by step

1. Import OInput from the ooko-ui/input public subpath.
2. Bind application state with v-model and provide the required label.
3. Add native attributes, guidance, and validation state directly on the component as needed.

Example

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

Email *

We will not share your address.

Interactive playground

Change the value, label, type, guidance, size, and input states. The preview updates immediately.

Example label

Helpful context appears here.

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

Props

Prop	Type	Default	Description
size	OokoFormControlSize	"md"	Controls the input's form-control scale.
modelValue	string	undefined	Current controlled value of the input.
label	string	undefined	Visible or visually hidden accessible label.
type	OInputType	"text"	Native type used by the text input.
id	string	undefined	Native input identifier. A hydration-safe identifier is generated when omitted.
name	string	undefined	Native form field name and OForm validation key.
hint	string	undefined	Persistent guidance displayed below the input.
error	string	undefined	Controlled validation error displayed below the input.
validation	OokoValidationBinding	undefined	Validation binding created by useOokoValidation.
hideLabel	boolean	false	Visually hides the label while preserving its accessible name.
required	boolean	false	Marks the native input as required.
disabled	boolean	false	Disables the native input.
readonly	boolean	false	Makes the native input read-only.
icon	Component	undefined	Vue component rendered as a decorative input icon.
iconPosition	OFieldIconPosition	"leading"	Places the icon before or after the input.

Events

Event	Payload	Description
update:modelValue	string	Emits the current string value after native input.

Slots

Slot	Props	Description
icon	none	Provides custom decorative icon markup and overrides the icon prop.

Related types

Type	Definition
OInputType	type OInputType = "email" | "password" | "search" | "tel" | "text" | "url";
OokoFormControlSize	type OokoFormControlSize = "sm" | "md";

CSS custom properties

Custom property	Default	Description
--o-input-gap	var(--o-space-1)	Sets the vertical space between field content.
--o-input-height	var(--o-control-form-height-md)	Sets the minimum input height.
--o-input-padding-inline	var(--o-space-3)	Sets the input's inline padding.
--o-input-icon-gap	var(--o-space-2)	Sets the space between the icon and input.
--o-input-icon-size	1.25rem	Sets the decorative icon size.
--o-input-border	1px solid var(--o-border-color-control)	Sets the input border shorthand while preserving state colors by default.
--o-input-border-radius	var(--o-radius-control)	Sets the input corner radius.
--o-input-focus-width	0.1875rem	Sets the visible focus outline width.
--o-input-focus-style	solid	Sets the visible focus outline style.
--o-input-focus-offset	0.125rem	Sets the distance between the input and its focus outline.
--o-input-disabled-opacity	0.5	Sets the opacity of the complete disabled field.

Override example

:root {
  --o-input-height: 3rem;
  --o-input-border-radius: var(--o-radius-round);
}

Accessibility

• label is associated with the native input through matching for and id values.
• hideLabel uses a visually hidden treatment and never removes the accessible name.
• Hint and validation identifiers are merged with a consumer-provided aria-describedby value.
• Invalid fields expose aria-invalid="true"; the inline error is announced through a polite live region and remains visible text rather than color alone.
• Required, disabled, and read-only behavior uses native input attributes.
• Decorative icons are hidden from assistive technologies and never replace the label.
• Keyboard focus receives a visible outline, and forced-colors mode receives explicit borders.
• Generated identifiers use Vue's hydration-safe useId() API.

Behavior and edge cases

• The component accepts text-like input types only and always emits a string. Numeric, date, choice, and file controls require separate value contracts.
• Native attributes and listeners such as autocomplete, inputmode, pattern, maxlength, placeholder, aria-*, @input, and @change are forwarded to the input.
• Consumer class and style attributes apply to the complete field root instead of the inner input.
• Native constraints are first displayed on blur, then refreshed during correction and on OForm submission.
• Custom rules can be passed directly through validation or resolved from the nearest validation-enabled OForm by name. A direct binding takes precedence.
• The controlled error prop takes precedence over native validation and must be cleared by the parent. It also takes presentation precedence over custom results. Reset does not clear it.
• A placeholder does not replace the required label prop.
• The icon slot overrides the icon prop. iconPosition has no visual effect without an icon.
• App defaults may configure size and iconPosition; the resolved size is propagated to the internal OField.