Input

A text field component with label, hint, and validation.

vu-input · @velkin/react/input

Copy page

Import

React

npm i @velkin/react

import { VuInput } from "@velkin/react/input";

Examples

API

Props

Prop	Type	Default	Description
variant	VuInputVariant	"default"	Field chrome recipe. Default: `"default"`.
tone	VuInputTone	"normal"	Neutral chrome weight. Default: `"normal"`.
size	VuInputSize	"md"	Field scale. Default: `"md"`.
radius	VuInputRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
block	`boolean`	false	Stretches the field to the container width. Default: `false`.
name	`string`	—	Form field name. Default: `""`.
defaultValue	`string`	—	Uncontrolled initial value; HTML attribute is `value`. Default: `""`.
formId	`string \| null`	—	ID of an external `<form>`; HTML attribute is `formid`. Default: `null`.
disabled	`boolean`	—	Non-interactive state. Default: `false`.
readonly	`boolean`	—	Read-only; keeps focus without editing. Default: `false`.
required	`boolean`	false	Marks the field required for form validation. Default: `false`.
requiredMessage	`string`	—	Message when `required` fails. Default: `"This field is required."`.
value	VuInputValue	""	Current value; `number` when `type="number"`.
placeholder	`string`	""	Placeholder or file-input fallback label.
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
type	VuInputType	"text"	Native type, or `textarea` / `file`. Default: `"text"`.
validations	VuInputValidation[]	—	Custom validators returning `true` or an error string.
compact	`boolean`	false	Tighter vertical spacing. Default: `false`.
loading	`boolean`	false	Shows a trailing spinner. Default: `false`.
showErrors	`boolean`	false	Shows validation messages after `validationActive`. Default: `false`.
clearable	`boolean`	false	Shows a clear button when the field has a value. Default: `false`.
showNumberButtons	`boolean`	false	Shows +/- controls for `type="number"`. Default: `false`.
showPasswordToggle	`boolean`	true	Shows a password visibility toggle. Default: `true`.
step	`null \| string`	null	Native `step` for number inputs.
min	`null \| string`	null	Native `min` constraint.
max	`null \| string`	null	Native `max` constraint.
autocapitalize	`string`	"off"	Native `autocapitalize`. Default: `"off"`.
autocomplete	`string`	"off"	Native `autocomplete`. Default: `"off"`.
spellcheck	`boolean`	false	Native `spellcheck`. Default: `false`.
dir	`string`	"ltr"	Text direction. Default: `"ltr"`.
rows	`number`	6	Textarea row count. Default: `6`.
resizable	`string`	"none"	Textarea resize mode. Default: `"none"`.
accept	`string`	""	File input accept filter.
multiple	`boolean`	false	Allows multiple files when `type="file"`. Default: `false`.
inputmode	`null \| string`	null	Native `inputmode` hint.
enterkeyhint	`null \| string`	null	Native `enterkeyhint` for virtual keyboards.
pattern	`null \| string`	null	Native `pattern` validation regex.
minlength	`null \| number`	null	Native minimum string length.
maxlength	`null \| number`	null	Native maximum string length.
list	`null \| string`	null	ID of a `<datalist>` to associate.
nativeSize	`null \| number`	null	Native `size` attribute (character width).
autofocus	`boolean`	false	Focuses the control on connect. Default: `false`.
capture	`boolean`	false	Enables capture on file inputs. Default: `false`.
ariaLabel	`string`	""	Accessible name when no visible label is present.
ariaLabelledby	`null \| string`	null	IDs of elements that label the control.
id	`string`	""	Host id; also prefixes internal control ids when set.
validationActive	`boolean`	false	Shows validation affordances after interaction. Default: `false`.
invalid	`boolean`	false	Reflects validation failure state. Default: `false`.

Events

Event	Detail	Description
vu-change	VuInputChangeDetail	When the value updates.
vu-clear	VuInputClearDetail	After the value is cleared.
vu-invalid	VuInputInvalidDetail	When validation messages are recomputed.
vu-file	VuInputFileDetail	After file selection changes.

Slots

Slot	Description
label	Rich label markup; takes precedence over string `label` when assigned.
hint	Optional helper copy (HTML); overrides string `hint` when assigned.
error	Replaces default validation message list when assigned.
start	Leading icon or affix inside the field container.
end	Trailing icon or affix inside the field container.

CSS parts

Part	Description
field	Column stacking label, control row, hint, and error.
label	Label wired to the native control.
start	Leading affix wrapper.
end	Trailing affix wrapper.
container	Field chrome wrapping the native control and actions.
input	Native `<input>` or `<textarea>`.
toggle-password	Password visibility toggle.
clear-button	Clear value control.
loading-indicator	Loading spinner on the trailing edge.
number-stepper	Increment/decrement button group for `type="number"`.
button	Shared part on stepper buttons.
button--decrease	Decrease button.
button--increase	Increase button.
hint	Helper text region.
error-message	Validation error region.
error-line	One default validation string.
file-info	Selected file count and size readout.
file-label	Visible label for file inputs.

Methods

Method	Description
validateInput	- Recomputes validation messages and returns whether the field is valid.
clear	- Clears the value and emits `vu-clear`.
focus	- Focuses the native control.

Types

Name	Definition
number \| null	`null \| number`
string \| null	`null \| string`
VuInputChangeDetail	`{ value: string \| number; previous: string \| number; }`
VuInputClearDetail	`{ value: string \| number; }`
VuInputFileDetail	`{ files: File[]; fileName: string; totalSize: number; fileCount: number; }`
VuInputInvalidDetail	`{ errors: string[]; }`
VuInputRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuInputSize	`"sm" \| "md" \| "lg"`
VuInputTone	`"subtle" \| "normal" \| "strong"`
VuInputType	`string`
VuInputValue	`null \| string \| number`
VuInputVariant	`"outline" \| "default" \| "underline"`

Import

React

API

Props

Prop	Type	Default	Description
variant	VuInputVariant	"default"	Field chrome recipe. Default: `"default"`.
tone	VuInputTone	"normal"	Neutral chrome weight. Default: `"normal"`.
size	VuInputSize	"md"	Field scale. Default: `"md"`.
radius	VuInputRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
block	`boolean`	false	Stretches the field to the container width. Default: `false`.
name	`string`	—	Form field name. Default: `""`.
defaultValue	`string`	—	Uncontrolled initial value; HTML attribute is `value`. Default: `""`.
formId	`string \| null`	—	ID of an external `<form>`; HTML attribute is `formid`. Default: `null`.
disabled	`boolean`	—	Non-interactive state. Default: `false`.
readonly	`boolean`	—	Read-only; keeps focus without editing. Default: `false`.
required	`boolean`	false	Marks the field required for form validation. Default: `false`.
requiredMessage	`string`	—	Message when `required` fails. Default: `"This field is required."`.
value	VuInputValue	""	Current value; `number` when `type="number"`.
placeholder	`string`	""	Placeholder or file-input fallback label.
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
type	VuInputType	"text"	Native type, or `textarea` / `file`. Default: `"text"`.
validations	VuInputValidation[]	—	Custom validators returning `true` or an error string.
compact	`boolean`	false	Tighter vertical spacing. Default: `false`.
loading	`boolean`	false	Shows a trailing spinner. Default: `false`.
showErrors	`boolean`	false	Shows validation messages after `validationActive`. Default: `false`.
clearable	`boolean`	false	Shows a clear button when the field has a value. Default: `false`.
showNumberButtons	`boolean`	false	Shows +/- controls for `type="number"`. Default: `false`.
showPasswordToggle	`boolean`	true	Shows a password visibility toggle. Default: `true`.
step	`null \| string`	null	Native `step` for number inputs.
min	`null \| string`	null	Native `min` constraint.
max	`null \| string`	null	Native `max` constraint.
autocapitalize	`string`	"off"	Native `autocapitalize`. Default: `"off"`.
autocomplete	`string`	"off"	Native `autocomplete`. Default: `"off"`.
spellcheck	`boolean`	false	Native `spellcheck`. Default: `false`.
dir	`string`	"ltr"	Text direction. Default: `"ltr"`.
rows	`number`	6	Textarea row count. Default: `6`.
resizable	`string`	"none"	Textarea resize mode. Default: `"none"`.
accept	`string`	""	File input accept filter.
multiple	`boolean`	false	Allows multiple files when `type="file"`. Default: `false`.
inputmode	`null \| string`	null	Native `inputmode` hint.
enterkeyhint	`null \| string`	null	Native `enterkeyhint` for virtual keyboards.
pattern	`null \| string`	null	Native `pattern` validation regex.
minlength	`null \| number`	null	Native minimum string length.
maxlength	`null \| number`	null	Native maximum string length.
list	`null \| string`	null	ID of a `<datalist>` to associate.
nativeSize	`null \| number`	null	Native `size` attribute (character width).
autofocus	`boolean`	false	Focuses the control on connect. Default: `false`.
capture	`boolean`	false	Enables capture on file inputs. Default: `false`.
ariaLabel	`string`	""	Accessible name when no visible label is present.
ariaLabelledby	`null \| string`	null	IDs of elements that label the control.
id	`string`	""	Host id; also prefixes internal control ids when set.
validationActive	`boolean`	false	Shows validation affordances after interaction. Default: `false`.
invalid	`boolean`	false	Reflects validation failure state. Default: `false`.

Events

Event	Detail	Description
vu-change	VuInputChangeDetail	When the value updates.
vu-clear	VuInputClearDetail	After the value is cleared.
vu-invalid	VuInputInvalidDetail	When validation messages are recomputed.
vu-file	VuInputFileDetail	After file selection changes.

Slots

Slot	Description
label	Rich label markup; takes precedence over string `label` when assigned.
hint	Optional helper copy (HTML); overrides string `hint` when assigned.
error	Replaces default validation message list when assigned.
start	Leading icon or affix inside the field container.
end	Trailing icon or affix inside the field container.

CSS parts

Part	Description
field	Column stacking label, control row, hint, and error.
label	Label wired to the native control.
start	Leading affix wrapper.
end	Trailing affix wrapper.
container	Field chrome wrapping the native control and actions.
input	Native `<input>` or `<textarea>`.
toggle-password	Password visibility toggle.
clear-button	Clear value control.
loading-indicator	Loading spinner on the trailing edge.
number-stepper	Increment/decrement button group for `type="number"`.
button	Shared part on stepper buttons.
button--decrease	Decrease button.
button--increase	Increase button.
hint	Helper text region.
error-message	Validation error region.
error-line	One default validation string.
file-info	Selected file count and size readout.
file-label	Visible label for file inputs.

Methods

Method	Description
validateInput	- Recomputes validation messages and returns whether the field is valid.
clear	- Clears the value and emits `vu-clear`.
focus	- Focuses the native control.

Types

Name	Definition
number \| null	`null \| number`
string \| null	`null \| string`
VuInputChangeDetail	`{ value: string \| number; previous: string \| number; }`
VuInputClearDetail	`{ value: string \| number; }`
VuInputFileDetail	`{ files: File[]; fileName: string; totalSize: number; fileCount: number; }`
VuInputInvalidDetail	`{ errors: string[]; }`
VuInputRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuInputSize	`"sm" \| "md" \| "lg"`
VuInputTone	`"subtle" \| "normal" \| "strong"`
VuInputType	`string`
VuInputValue	`null \| string \| number`
VuInputVariant	`"outline" \| "default" \| "underline"`

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse