Serial

A serial input component for license keys with group separators.

vu-serial · @velkin/react/serial

Copy page

Import

React

npm i @velkin/react

import { VuSerial } from "@velkin/react/serial";

Examples

API

Props

Prop	Type	Default	Description
name	`string`	—	Form field name for submit (`name` attr).
defaultvalue	`string`	—	Restored on `<form reset>` (`defaultvalue` attr).
formid	`string`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	—	Non-interactive; blocks cell entry (`disabled` attr).
readonly	`boolean`	—	Focusable but cannot change cells (`readonly` attr).
required	`boolean`	—	Blocks valid submit when incomplete (`required` attr).
requiredmessage	`string`	—	Custom `valueMissing` message (`requiredmessage` attr).
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
id	`string`	""	Host id for label `for` / `aria-*` wiring.
variant	VuSerialVariant	"default"	Field chrome recipe. Default: `"default"`.
tone	VuSerialTone	"normal"	Neutral surface weight. Default: `"normal"`.
size	VuSerialSize	"md"	Cell scale. Default: `"md"`.
radius	VuSerialRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
block	`boolean`	false	Stretches the cell row to the container width. Default: `false`.
compact	`boolean`	false	Tighter label/hint/error spacing. Default: `false`.
length	`number`	10	Total number of character boxes. Default: `10`.
separator	`string`	"-"	Separator character between groups. Default: `"-"`.
separatorpositions	`number[]`	—	Cell indices after which a separator is shown (JS-only).
alphanumeric	`boolean`	false	Allows letters in addition to digits. Default: `false`.
value	`string`	""	Canonical serial string (may include separators). Default: `""`.
withseparator	`boolean`	—	Includes separators in `value` and form submission. Default: `false`.
masked	`boolean`	false	Masks cell glyphs (`type="password"`). Default: `false`.
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
incompletemessage	`string`	—	Error when some cells are filled but not all; empty uses default.
arialabel	`string`	—	Names the row when no visible label is present.
separatorPositions	`number[]`	[3]	Cell indices after which a separator is inserted (e.g. `[3, 6]`).
withSeparator	`boolean`	false	Includes separators in `value` and form submission.
incompleteMessage	`string`	""	Error when some cells are filled but not all; empty uses a default.
ariaLabel	`string`	""	Names the row when no visible label is present.
showErrors	`boolean`	false	Shows validation after activation.
validationActive	`boolean`	false	Drives invalid styling after activation.

Events

Event	Detail	Description
vu-change	VuSerialChangeDetail	Committed value change (`detail.value`).
vu-invalid	VuSerialInvalidDetail	When validation messages are recomputed.
vu-clear	VuSerialClearDetail	After `reset()` syncs from `defaultValue`.

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.

CSS parts

Part	Description
field	Column stacking label, cells row, hint, and error.
label	Label element above the serial row.
cells	Flex row wrapping groups and separators (`role="group"`).
group	Tight cluster of cells between separators.
separator	Visual separator glyph between groups.
cell	One serial character input.
hint	Neutral helper text under the row.
error-message	Region for `slot="error"` or stacked default validation lines.
error-line	One default validation string when `slot="error"` is empty.
text	String `label` text when the `label` slot is empty.

Methods

Method	Description
reset	- Clears cells to `defaultValue` and dispatches `vu-clear`.
focusFirst	- Focuses the first serial cell.
validateInput	- Runs validators and syncs validity.

Types

Name	Definition
VuSerialChangeDetail	`{ value: string; }`
VuSerialClearDetail	`{ value: string; }`
VuSerialInvalidDetail	`{ errors: string[]; }`
VuSerialRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuSerialSize	`"sm" \| "md" \| "lg"`
VuSerialTone	`"subtle" \| "normal" \| "strong"`
VuSerialVariant	`"outline" \| "default" \| "underline"`

Import

React

API

Props

Prop	Type	Default	Description
name	`string`	—	Form field name for submit (`name` attr).
defaultvalue	`string`	—	Restored on `<form reset>` (`defaultvalue` attr).
formid	`string`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	—	Non-interactive; blocks cell entry (`disabled` attr).
readonly	`boolean`	—	Focusable but cannot change cells (`readonly` attr).
required	`boolean`	—	Blocks valid submit when incomplete (`required` attr).
requiredmessage	`string`	—	Custom `valueMissing` message (`requiredmessage` attr).
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
id	`string`	""	Host id for label `for` / `aria-*` wiring.
variant	VuSerialVariant	"default"	Field chrome recipe. Default: `"default"`.
tone	VuSerialTone	"normal"	Neutral surface weight. Default: `"normal"`.
size	VuSerialSize	"md"	Cell scale. Default: `"md"`.
radius	VuSerialRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
block	`boolean`	false	Stretches the cell row to the container width. Default: `false`.
compact	`boolean`	false	Tighter label/hint/error spacing. Default: `false`.
length	`number`	10	Total number of character boxes. Default: `10`.
separator	`string`	"-"	Separator character between groups. Default: `"-"`.
separatorpositions	`number[]`	—	Cell indices after which a separator is shown (JS-only).
alphanumeric	`boolean`	false	Allows letters in addition to digits. Default: `false`.
value	`string`	""	Canonical serial string (may include separators). Default: `""`.
withseparator	`boolean`	—	Includes separators in `value` and form submission. Default: `false`.
masked	`boolean`	false	Masks cell glyphs (`type="password"`). Default: `false`.
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
incompletemessage	`string`	—	Error when some cells are filled but not all; empty uses default.
arialabel	`string`	—	Names the row when no visible label is present.
separatorPositions	`number[]`	[3]	Cell indices after which a separator is inserted (e.g. `[3, 6]`).
withSeparator	`boolean`	false	Includes separators in `value` and form submission.
incompleteMessage	`string`	""	Error when some cells are filled but not all; empty uses a default.
ariaLabel	`string`	""	Names the row when no visible label is present.
showErrors	`boolean`	false	Shows validation after activation.
validationActive	`boolean`	false	Drives invalid styling after activation.

Events

Event	Detail	Description
vu-change	VuSerialChangeDetail	Committed value change (`detail.value`).
vu-invalid	VuSerialInvalidDetail	When validation messages are recomputed.
vu-clear	VuSerialClearDetail	After `reset()` syncs from `defaultValue`.

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.

CSS parts

Part	Description
field	Column stacking label, cells row, hint, and error.
label	Label element above the serial row.
cells	Flex row wrapping groups and separators (`role="group"`).
group	Tight cluster of cells between separators.
separator	Visual separator glyph between groups.
cell	One serial character input.
hint	Neutral helper text under the row.
error-message	Region for `slot="error"` or stacked default validation lines.
error-line	One default validation string when `slot="error"` is empty.
text	String `label` text when the `label` slot is empty.

Methods

Method	Description
reset	- Clears cells to `defaultValue` and dispatches `vu-clear`.
focusFirst	- Focuses the first serial cell.
validateInput	- Runs validators and syncs validity.

Types

Name	Definition
VuSerialChangeDetail	`{ value: string; }`
VuSerialClearDetail	`{ value: string; }`
VuSerialInvalidDetail	`{ errors: string[]; }`
VuSerialRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuSerialSize	`"sm" \| "md" \| "lg"`
VuSerialTone	`"subtle" \| "normal" \| "strong"`
VuSerialVariant	`"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