Inputs@knitui/components

PinInput

PinInput renders a row of single-character inputs for codes and OTP entry. Focus advances automatically between fields. type controls accepted characters, mask hides the value, and size sets the field metrics.

WebiOSAndroid1 style slots19 own props11 examples

Stories Source Tests Open in Storybook

import { PinInput } from "@knitui/components";

Playground

Loading playground…

lengthNumber of individual input fields.

typeCharacter set accepted by each field.

sizeControls each field's width/height and font size.

maskRenders fields as password inputs.

false

disabled

false

error

false

readOnly

false

placeholder

manageFocusAdvance focus automatically to the next field after entry.

true

oneTimeCodeSets autocomplete="one-time-code" on each field.

true

Playground

<PinInput
  length={4}
  type="alphanumeric"
  size="sm"
  mask={false}
  disabled={false}
  error={false}
  readOnly={false}
  placeholder="○"
  manageFocus
  oneTimeCode
/>

Examples

Sizes

The seven token sizes from xxs to xxl, rendered side by side.

Loading example…

SizesSource Storybook

Shadows

Each elevation of the inherited shadow prop applied to the field row.

Loading example…

ShadowsSource Storybook

Disabled

Disabled state — all fields reject input and appear dimmed.

Loading example…

DisabledSource Storybook

With Error

Error state — every field receives error styling and aria-invalid.

Loading example…

With ErrorSource Storybook

Masked

Masked inputs — characters are hidden behind the platform password glyph.

Loading example…

MaskedSource Storybook

Number Type

Numeric-only mode — only digit characters (0–9) are accepted.

Loading example…

Number TypeSource Storybook

Six Digits

Six-digit code length, suitable for TOTP or SMS OTP flows.

Loading example…

Six DigitsSource Storybook

Controlled

Controlled component — the parent holds the value in state and logs onComplete.

Loading example…

ControlledSource Storybook

Read Only

Read-only — the pre-filled value is visible but cannot be changed.

Loading example…

Read OnlySource Storybook

Styles

Per-slot styles targets individual parts — here the field spread onto every per-character input.

Loading example…

StylesSource Storybook

Props

Prop	Type	Default	Description
`ariaLabel`	`string \| undefined`	`"PinInput"`	`aria-label` applied to every input.
`autoFocus`	`boolean \| undefined`	`false`	Focuses the first input on mount.
`defaultValue`	`string \| undefined`	—	Uncontrolled component default value.
`disabled` system	`boolean \| undefined`	`false`	Disables every input.
`error`	`boolean \| undefined`	`false`	Applies error styles + `aria-invalid` to every input.
`gap`	`((number \| SpaceTokens) & (string \| number)) \| undefined`	`"$xs"`	Gap between inputs. Token, CSS value or number.
`getInputProps`	`((index: number) => Partial<InputProps>) \| undefined`	—	Props applied to each input, by index.
`id`	`string \| undefined`	—	Base id used to generate per-input ids.
`inputMode`	`PinInputMode \| undefined`	—	Host `inputmode` attribute, inferred from `type` if unset.
`inputType`	`HTMLInputTypeAttribute \| undefined`	—	Host `type` attribute, inferred from `type`/`mask` if unset.
`length`	`number \| undefined`	`4`	Number of individual input fields.
`manageFocus`	`boolean \| undefined`	`true`	Advance focus automatically to the next field after entry.
`mask`	`boolean \| undefined`	`false`	Renders fields as password inputs.
`onChange`	`((value: string) => void) \| undefined`	—	Called when the value changes.
`onComplete`	`((value: string) => void) \| undefined`	—	Called once when every input has a value.
`oneTimeCode`	`boolean \| undefined`	`true`	Sets autocomplete="one-time-code" on each field.
`placeholder`	`string \| undefined`	`"○"`	Inputs placeholder.
`radius` system	`string \| number \| undefined`	—	Border radius of each input.
`readOnly`	`boolean \| undefined`	`false`	When set, the user cannot edit the value.
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined`	—
`size` system	`InputSize \| undefined` xxs · xs · sm · md · lg · xl · xxl	`"md"`	Controls each field's width/height and font size.
`styles` system	`SlotStyles<PinInputStyles> \| undefined`	—	Per-slot style sugar — props spread onto each per-character `Input`.
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element
`type`	`PinInputType \| undefined` alphanumeric · number	`"alphanumeric"`	Character set accepted by each field.
`value`	`string \| undefined`	—	Controlled component value.

Style slots

Every part of PinInput can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`field`	`styles={{ field: { … } }}`

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<TamaguiElement> \| undefined`

Plus 494 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.