Component size, gzipped: 27kb

Pin Code

API

The PinCode component is optimized for entering sequences of digits. The most common application is for entering single-use security codes. It is optimized for entering digits quickly.

Examples

Basic usage

Each input collects one digit at a time. When a digit is entered, focus transfers to the next input in the sequence, until every input is filled in. A few things to note:

  1. You canʼt enter anything other than a digit.
  2. You can only enter one character per input.
  3. To overwrite the value of an input, you donʼt need to select the text in the input. If you type a digit while the input is focused, the input will update. This is an optimization for quickly editing the inputs.
  4. Pressing Delete when there is nothing in the input will transfer focus to, and clear the value of, the previous input (if any). This avoids the need to explicitly Shift+Tab & Delete.

Code length

PinCode expects an array of strings for the values prop. The number of inputs rendered will match the length of the array.

Passing id and name

You can pass an individual id or name prop. name will be shared amongst the inputs, meaning they will each have their name set to this value. id will have an index appended to whatever string you provide and passed to the respective input. In the above example, the resulting ids are foo-0, foo-1, foo-2, and foo-3 and each input has the name pin-code.

States



PinCode accepts most of the same boolean props as our other inputs: disabled, error, positive, etc.

Sizes



You can control the size of the inputs with the size prop.

Changing the placeholder

If you donʼt like the default placeholder (), you can change that too. Notice how each placeholder disappears when any of the inputs have focus.

Disable focus management

You can disable PinCodeʼs built-in focusing logic by toggling the manageFocus prop. It defaults to true, which makes it so that when an input receives a digit, focus is automatically changed to the next input. It also transfers focus to a previous input when Delete is pressed with focus on an empty input. Set manageFocus to false if, for some reason, you donʼt want this nifty behavior. You can use the onChange handler to implement your own thing.

The main Event

The object passed to onChange has two properties. values is the new array of strings that PinCode thinks you should update your state with. Of course, you can decide not to use those values. If, for some reason, you do not want to use values, the onChange object also includes an event property which references the original input change event.

We do not envision a lot of scenarios where you would need this level of control- but just in case, it is there for you. Note, if you do decide to go off the rails with event, you may want to turn off manageFocus as well. Otherwise you may have focus jumping around in ways inconsistent with your customizations.

Autofocus

There is a decent chance that if you are using PinCode you want it to be focused from the start. Simply set autoFocus to true to focus the first input upon initial mounting of the component.

In the example above, click Mount PinCode to ...mount the PinCode component. With autoFocus toggled on, the first input receives focus immediately.

Once things are filled in

It is a common pattern to immediately submit the userʼs input once the full pin code has been entered. In the above example, we shift focus to the submit button once all of our inputs have been filled in. Keep in mind that folks may have mistyped a digit so auto-submitting might be a bit aggressive.

Autocomplete 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 what if a user wants to copy and paste a value in? Or what if the userʼs browser can autocomplete verification codes.

If one of the individual inputs receives a longer string, PinCode does some basic validation (is the length right? does it contain only digits?) to see if it can fill all the inputs. If things seem promising, PinCode will call onChange will all of the values updated.

Stateful (uncontrolled) usage

As with many of our components, there is also an uncontrolled version, StatefulPinCode, which manages its own state. The default code length for this component is four, but you can change that by passing in an array of a different length to initialState.

API

Pin Code props

NameTypeDescription
aria-describedby
string
Sets aria-describedby attribute.
aria-label
string
Sets aria-label attribute.
aria-labelledby
string
Sets aria-labelledby attribute.
autoComplete
string
Determines if browser should provide value suggestions.
autoFocus
boolean
If true the input will be focused on the first mount.
disabled
boolean
Renders component in disabled state.
error
boolean
Renders component in error state.
id
string
Id attribute value to be added to the input element and as a label's for attribute value.
max
string
max value when used as input type=number
min
string
min value when used as input type=number
name
string
Name attribute.
onBlur
function
Called the onBlur event triggers.
onChange
function
Called when input value is changed.
onFocus
function
Called the onFocus event triggers.
onKeyDown
function
Called the onKeyDown event triggers.
onKeyPress
function
Called the onKeyPress event triggers.
onKeyUp
function
Called the onKeyUp event triggers.
overrides
custom
Lets you customize all aspects of the component.
placeholder
string
Displayed when the pin code is not entered yet.
positive
boolean
Renders component in positive state.
required
boolean
Renders component in required state.
size
enum
Renders component in provided size.
values
array
PinCode value attribute.

Pin Code exports

You can import this module like so:

import {PinCode} from 'baseui/pin-code'

It exports the following components or utility functions: