PinInput

PinInput is a component used to capture pin codes or OTP (One-Time Password) inputs.

<PinInput.Root />

Usage

import { PinInput } from "@yamada-ui/react"

import { PinInput } from "@/components/ui"

import { PinInput } from "@workspaces/ui"

<PinInput.Root />

Change Variant

<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant) => <PinInput.Root key={variant} variant={variant} />}
  </For>
</VStack>

Change Size

<VStack>
  <For each={["xs", "sm", "md", "lg", "xl"]}>
    {(size) => <PinInput.Root key={size} size={size} />}
  </For>
</VStack>

Change Color Scheme

<VStack>
  <For each={["green", "orange"]}>
    {(colorScheme) => (
      <PinInput.Root key={colorScheme} colorScheme={colorScheme} />
    )}
  </For>
</VStack>

Set Default Value

To set a default value, set a string to defaultValue.

<VStack>
  <For each={["1234", "123"]}>
    {(defaultValue) => (
      <PinInput.Root key={defaultValue} defaultValue={defaultValue} />
    )}
  </For>
</VStack>

Change Placeholder

To change the placeholder, set a string to placeholder.

<PinInput.Root placeholder="💩" />

Change Number of Fields

To change the number of fields, set a number to items.

<VStack>
  <For each={[3, 4, 5, 6]}>
    {(items) => <PinInput.Root key={items} items={items} />}
  </For>
</VStack>

Change Type

By default, only numeric input is allowed. To support alphanumeric, set type to alphanumeric.

<PinInput.Root type="alphanumeric" />

Use as One-Time Password

To use as a one-time password (autocomplete="one-time-code"), set otp to true.

<PinInput.Root otp />

Mask Entered Value

To mask the entered value, set mask to true.

<PinInput.Root mask />

Disabled

To disable the input, set disabled to true.

<PinInput.Root>
  <For each={[0, 1, 2, 3]}>
    {(index) => <PinInput.Field key={index} index={index} disabled />}
  </For>
</PinInput.Root>

Read-Only

To make read-only, set readOnly to true.

<PinInput.Root>
  <For each={[0, 1, 2, 3]}>
    {(index) => <PinInput.Field key={index} index={index} readOnly />}
  </For>
</PinInput.Root>

Invalid

To make invalid, set invalid to true.

<PinInput.Root>
  <For each={[0, 1, 2, 3]}>
    {(index) => <PinInput.Field key={index} index={index} invalid />}
  </For>
</PinInput.Root>

Change Border Color

To change the border color, set focusBorderColor or errorBorderColor to the color.

<VStack>
  <PinInput.Root focusBorderColor="green.500" />
  <PinInput.Root errorBorderColor="orange.500" invalid />
</VStack>

Set Action on Completion

To set the action on completion, use the onComplete property.

const { page } = useLoading()

return <PinInput.Root onComplete={() => page.start({ duration: 5000 })} />

If you use this code, you need to add "use client" to the top of the file.

By default, when a field is entered, the focus automatically moves to the next field. Also, when the BackSpace key is pressed, the focus moves to the previous field. To disable this control, set manageFocus to false.

<PinInput.Root manageFocus={false} />

Customize Field

<PinInput.Root>
  <For each={[0, 1, 2, 3]}>
    {(index) => (
      <PinInput.Field
        key={index}
        index={index}
        _placeholder={{ color: "blue.500" }}
      />
    )}
  </For>
</PinInput.Root>

Control

const { page } = useLoading()
const [value, onChange] = useState("")

const onComplete = () => page.start({ duration: 5000 })

return (
  <PinInput.Root value={value} onChange={onChange} onComplete={onComplete} />
)

If you use this code, you need to add "use client" to the top of the file.

Props

PinInput.Root

Prop	Default	Type / Description
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`size`	`"md"`	`"2xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` The size of the component.
`variant`	`"outline"`	`"filled" \| "flushed" \| "outline" \| "plain"` The variant of the component.
`align`	-	`"-moz-initial" \| "anchor-center" \| "baseline" \| "center" \| "end" \| "flex-end" \| "flex-start" \| "inherit" \| "initial" \| "normal" ...` The CSS `align-items` property.
`basis`	-	`"-moz-fit-content" \| "-moz-initial" \| "-moz-max-content" \| "-moz-min-content" \| "-webkit-auto" \| "0.5" \| "1.5" \| "1" \| "1/12" \| "1/2" ...` The CSS `flex-basis` property.
`defaultValue`	-	`string` The initial value of the pin input.
`direction`	-	`"-moz-initial" \| "column-reverse" \| "column" \| "inherit" \| "initial" \| "revert-layer" \| "revert" \| "row-reverse" \| "row" \| "unset" ...` The CSS `flex-direction` property.
`disabled`	`false`	`boolean` If `true`, the field will be disabled.
`errorBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is invalid.
`focusBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is focused.
`invalid`	`false`	`boolean` If `true`, the field will be invalid.
`items`	`4`	`number` The number of inputs to display.
`justify`	-	`"-moz-initial" \| "center" \| "end" \| "flex-end" \| "flex-start" \| "inherit" \| "initial" \| "left" \| "normal" \| "revert-layer" ...` The CSS `justify-content` property.
`manageFocus`	`true`	`boolean` If `true`, focus will move automatically to the next input once filled.
`mask`	-	`boolean` If `true`, the input's value will be masked just like `type=password`.
`onChange`	-	`(value: string) => void` Function called on input change.
`onComplete`	-	`(value: string) => void` Function called when all inputs have valid values.
`otp`	-	`boolean` If `true`, the pin input component signals to its fields that they should.
`placeholder`	`"◯"`	`string` The placeholder for the pin input.
`readOnly`	`false`	`boolean` If `true`, the field will be readonly.
`required`	`false`	`boolean` If `true`, the field will be required.
`shrink`	-	`"-moz-initial" \| "inherit" \| "initial" \| "revert-layer" \| "revert" \| "unset" \| number & {} ...` The CSS `flex-shrink` property.
`type`	`"number"`	`"alphanumeric" \| "number"` The type of values the pin-input should allow.
`value`	-	`string` The value of the pin input.
`wrap`	-	`"-moz-initial" \| "inherit" \| "initial" \| "nowrap" \| "revert-layer" \| "revert" \| "unset" \| "wrap-reverse" \| "wrap" ...` The CSS `flex-wrap` property.

PinInput.Field

Prop	Default	Type / Description
`as`	-	`As` The HTML element to render.
`asChild`	-	`boolean` Merges its props onto its immediate child.
`css`	-	`CSSObject \| CSSObject[]` The CSS object.
`colorScheme`	-	`"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` Set color scheme variables.
`size`	-	`"2xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` The size of the component.
`variant`	-	`"filled" \| "flushed" \| "outline" \| "plain"` The variant of the component.
`index`	-	`number` The index of the pin input field.
`errorBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is invalid.
`focusBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is focused.
`htmlSize`	-	`number` The native HTML `size` attribute to be passed to the `input`.
`invalid`	`false`	`boolean` If `true`, the field will be invalid.

Accessibility

If you are not using Field.Root, set aria-label or aria-labelledby to PinInput.Root.

<PinInput.Root aria-label="Please one-time password" />

<VStack gap="sm">
  <Text as="h3" id="label">
    Please one-time password
  </Text>

  <PinInput.Root aria-labelledby="label" />
</VStack>

Key	Description	State
`Tab`	Move the focus to the next item.	-
`ArrowRight`	Move the focus to the next item.	-
`ArrowLeft`	Move the focus to the previous item.	-

ARIA Roles and Attributes

Component	Role and Attributes	Usage
`PinInput.Root`	`role="group"`	Indicates that this is a group.
`PinInput.Field`	`aria-invalid`	Set to `"true"` if `invalid` is set.
	`aria-disabled`	Set to `"true"` if `disabled` is set.
	`aria-describedby`	If `PinInput.Field` is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`.
	`aria-readonly`	Set to `"true"` if `readOnly` is set.
	`aria-required`	Set to `"true"` if `required` is set.

Similar Components

Editable is a component used to obtain inline editable text input.

Input is a component used to obtain text input from the user.

NumberInput is a component used to obtain numeric input from the user.

PasswordInput is a component that allows users to input passwords with a visibility toggle.

Textarea is a component used to obtain multi-line text input.

FileInput is a component used for users to select files.

Autocomplete is a component used to display suggestions in response to user text input.

Checkbox is a component used for allowing users to select multiple values from multiple options.

Uses Components & Hooks

Input is a component used to obtain text input from the user.

Group is a component that groups and attaches multiple elements together.

Field is a component used to group form elements with label, helper message, error message, etc.

useDescendants is a custom hook that manages descendants.