Pin Input
The PinInput component is similar to the Input component, but is optimized for entering sequences of digits quickly.
Import
import { PinInput, PinInputField } from '@chakra-ui/react';
- PinInput: The component that provides context to all the pin-input fields.
- PinInputField: The text field that user types in - must be a direct child
of
PinInput
.
Usage
The most common use case of the pin input is for entering OTP or security codes.
Each input collects one character at a time. When a value is entered, focus is moved automatically to the next input, until all fields are filled.
Allowing Alphanumeric values
By default, the pin input accepts only number values. To add support for
alphanumeric values, pass the type
prop and set its value to either
alphanumeric
or number
.
Using fields as a one time password (OTP)
Use the otp
prop on PinInput
to set autocomplete="one-time-code"
for all
children PinInputField
components.
Masking the pin input's value
When collecting private or sensitive information using the pin input, you might
need to mask the value entered, similar to <input type="password"/>
.
Pass the mask
prop to PinInput
to achieve this.
Changing the size of the PinInput
The PinInput
component comes in four sizes. The default is md
.
xs
(24px
)sm
(32px
)md
(40px
)lg
(48px
)
Adding a defaultValue
You can set the defaultValue
of the PinInput if you wish:
Or even a partial defaultValue:
Changing the placeholder
To customize the default input placeholder (○
), pass the placeholder
prop
and set it to your desired placeholder.
Disable focus management
By default, PinInput
moves focus automatically to the next input once a field
is filled. It also transfers focus to a previous input when Delete is
pressed with focus on an empty input.
To disable this behavior, set manageFocus
to false
AutoFill and Copy + Paste
Try copying & pasting 1234
into any of the inputs in the example above.
By default, you can only change one input at a time, but if one of the input
field receives a longer string by pasting into it, PinInput
attempts to
validate the string and fill the other inputs.
Props
children
required
children
required
The children of the pin input component
ReactNode
autoFocus
autoFocus
If true
, the pin input receives focus on mount
boolean
colorScheme
colorScheme
Color Schemes for PinInput
are not implemented in the default theme. You can extend the theme to implement them.
string
defaultValue
defaultValue
The default value of the pin input
string
errorBorderColor
errorBorderColor
The border color when the input is invalid. Use color keys in `theme.colors` @example errorBorderColor = "red.500"
string
focusBorderColor
focusBorderColor
The border color when the input is focused. Use color keys in `theme.colors` @example focusBorderColor = "blue.500"
string
id
id
The top-level id string that will be applied to the input fields. The index of the input will be appended to this top-level id. @example if id="foo", the first input will have `foo-0`
string
isDisabled
isDisabled
If true
, the pin input component is put in the disabled state
boolean
isInvalid
isInvalid
If true
, the pin input component is put in the invalid state
boolean
manageFocus
manageFocus
If true
, focus will move automatically to the next input once filled
boolean
true
mask
mask
If true
, the input's value will be masked just like `type=password`
boolean
onChange
onChange
Function called on input change
((value: string) => void)
onComplete
onComplete
Function called when all inputs have valid values
((value: string) => void)
otp
otp
If true
, the pin input component signals to its fields that they should
use `autocomplete="one-time-code"`.
boolean
placeholder
placeholder
The placeholder for the pin input
string
size
size
"lg" | "md" | "sm" | "xs"
"md"
type
type
The type of values the pin-input should allow
"number" | "alphanumeric"
value
value
The value of the pin input. This is the value that will be returned when the pin input is filled
string
variant
variant
"outline" | "flushed" | "filled" | "unstyled"
"outline"
PinInputField
PinInputField composes Input
so you can pass all Input
props.
colorScheme
colorScheme
Color Schemes for Input
are not implemented in the default theme. You can extend the theme to implement them.
string
errorBorderColor
errorBorderColor
The border color when the input is invalid. Use color keys in `theme.colors` @example errorBorderColor = "red.500"
string
focusBorderColor
focusBorderColor
The border color when the input is focused. Use color keys in `theme.colors` @example focusBorderColor = "blue.500"
string
htmlSize
htmlSize
The native HTML size
attribute to be passed to the input
number
isDisabled
isDisabled
If true
, the form control will be disabled. This has 2 side effects:
- The FormLabel
will have `data-disabled` attribute
- The form element (e.g, Input) will be disabled
boolean
isInvalid
isInvalid
If true
, the form control will be invalid. This has 2 side effects:
- The FormLabel
and FormErrorIcon
will have `data-invalid` set to true
- The form element (e.g, Input) will have `aria-invalid` set to true
boolean
isReadOnly
isReadOnly
If true
, the form control will be readonly
boolean
isRequired
isRequired
If true
, the form control will be required. This has 2 side effects:
- The FormLabel
will show a required indicator
- The form element (e.g, Input) will have `aria-required` set to true
boolean
size
size
"lg" | "md" | "sm" | "xs"
"md"
variant
variant
"outline" | "filled" | "flushed" | "unstyled"
"outline"