If true
, the pin input receives focus on mount
Pin Input
The PinInput
component is similar to the Input component,
but it is optimized for entering sequences of digits.
The most common application is for entering OTP or security codes.
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#
Each input collects one value (number or alphanumeric) at a time. When a value is entered, focus is moved automatically to the next input, until all fields are filled.
<HStack><PinInput><PinInputField /><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack>
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
.
<HStack><PinInput type='alphanumeric'><PinInputField /><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack>
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.
<PinInput otp><PinInputField /><PinInputField /><PinInputField /><PinInputField /></PinInput>
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.
<HStack><PinInput type='alphanumeric' mask><PinInputField /><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack>
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
)
<Stack><HStack><PinInput size='xs'><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack><HStack><PinInput size='sm'><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack><HStack><PinInput size='md'><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack><HStack><PinInput size='lg'><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack></Stack>
Adding a defaultValue#
You can set the defaultValue
of the PinInput if you wish:
<HStack><PinInput defaultValue='234'><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack>
Or even a partial defaultValue:
<HStack><PinInput defaultValue='23'><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack>
Changing the placeholder#
To customize the default input placeholder (â—‹
), pass the placeholder
prop
and set it to your desired placeholder.
<HStack><PinInput placeholder='🥳'><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack>
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
<HStack><PinInput manageFocus={false}><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack>
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.
<HStack><PinInput><PinInputField /><PinInputField /><PinInputField /></PinInput></HStack>
Props#
autoFocus
autoFocus
boolean
children
children
The children of the pin input component
ReactNode
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
isFullWidth
isFullWidth
If true
, the input element will span the full width of its parent
@deprecated This component defaults to 100% width,
please use the props maxWidth
or width
to configure
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"