Pin Input

A component for entering and displaying a sequence of numeric or alphanumeric characters, often used for PINs or codes.

Label

Anatomy

Usage

<script>
  import {PinInput} from 'ui-ingredients';
</script>

<PinInput.Root>
  <PinInput.Label>Label</PinInput.Label>
  <PinInput.Input index={0} />
  <PinInput.Input index={1} />
  <PinInput.Input index={2} />
  <PinInput.Input index={3} />
  <PinInput.HiddenInput />
</PinInput.Root>

Usage with Field component

<script>
  import {PinInput} from 'ui-ingredients';
</script>

<Field.Root>
  <PinInput.Root>
    <PinInput.Label>Label</PinInput.Label>
    <PinInput.Input index={0} />
    <PinInput.Input index={1} />
    <PinInput.Input index={2} />
    <PinInput.Input index={3} />
    <PinInput.HiddenInput />
  </PinInput.Root>

  <Field.HelperText>This is a helper text</Field.HelperText>
  <Field.ErrorText>This is an error text</Field.ErrorText>
</Field.Root>

API Reference

Root

Prop	Default	Description
`autoFocus`		`boolean` Whether to auto-focus the first input.
`blurOnComplete`		`boolean` Whether to blur the input when the value is complete
`count`		`number` The number of inputs to render to improve SSR aria attributes. This will be required in next major version.
`defaultValue`		`string[]` The initial value of the the pin input when rendered. Use when you don't need to control the value of the pin input.
`disabled`		`boolean` Whether the inputs are disabled
`form`		`string` The associate form of the underlying input element.
`id`		`string` The unique identifier of the machine.
`ids`		`{ root?: string; hiddenInput?: string; label?: string; control?: string; input(id: string)?: string; }` The ids of the elements in the pin input. Useful for composition.
`invalid`		`boolean` Whether the pin input is in the invalid state
`mask`		`boolean` If `true`, the input's value will be masked just like `type=password`
`name`		`string` The name of the input element. Useful for form submission.
`onValueChange`		`(details: ValueChangeDetails) => void` Function called on input change
`onValueComplete`		`(details: ValueChangeDetails) => void` Function called when all inputs have valid values
`onValueInvalid`		`(details: ValueInvalidDetails) => void` Function called when an invalid value is entered
`otp`		`boolean` If `true`, the pin input component signals to its fields that they should use `autocomplete="one-time-code"`.
`pattern`		`string` The regular expression that the user-entered input value is checked against.
`placeholder`	`"○"`	`string` The placeholder text for the input
`readOnly`		`boolean` Whether the pin input is in the valid state
`required`		`boolean` Whether the pin input is required
`selectOnFocus`		`boolean` Whether to select input value when input is focused
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`type`	`"numeric"`	`"alphanumeric" \| "numeric" \| "alphabetic"` The type of value the pin-input should allow
`value`		`string[]` The controlled value of the the pin input.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-complete`	Present when the pin-input value is complete
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-part`	root
`data-readonly`	Present when read-only
`data-scope`	pin-input

ClearTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Control

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

HiddenInput

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Input

Prop	Default	Description
`index`		`number` The index of the input in the pin input.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-complete`	Present when the input value is complete
`data-disabled`	Present when disabled
`data-index`	The index of the item
`data-invalid`	Present when invalid
`data-part`	input
`data-scope`	pin-input

Label

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-complete`	Present when the label value is complete
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid
`data-part`	label
`data-readonly`	Present when read-only
`data-scope`	pin-input

Accessibility

Keyboard Support

Key	Description
ArrowLeft	Moves focus to the previous input
ArrowRight	Moves focus to the next input
Backspace	Deletes the value in the current input and moves focus to the previous input
Delete	Deletes the value in the current input
Control + V	Pastes the value into the input fields