react-pin-input-hook

React hook for entering a PIN code.

Installation

// with npm
npm install --save react-pin-input-hook

// with yarn
yarn add react-pin-input-hook

Usage example

Uncontrolled

import * as React from 'react'
import { usePinInput } from 'react-pin-input-hook'

function Component() {
  const { fields } = usePinInput({
    onComplete: (value) => {
      // Here you can make asynchronous requests to your API for verification.

      console.log(value)
    },
  })

  return (
    <div className='pin-input'>
      {fields.map((propsField, index) => (
        <input key={index} className='pin-input__field' {...propsField} />
      ))}
    </div>
  )
}

Controlled

import * as React from 'react'
import { usePinInput } from 'react-pin-input-hook'

function Component() {
  const [values, setValues] = React.useState(Array(6).fill(''))
  const { fields } = usePinInput({
    values,
    onChange: (values) => {
      setValues(values)
    },
  })

  return (
    <div className='pin-input'>
      {fields.map((propsField, index) => (
        <input key={index} className='pin-input__field' {...propsField} />
      ))}
    </div>
  )
}

Options

Prop Type Default Description
values string[] – Field values. If no values are passed, the default value defined in defaultValues is used.
onChange (values: string[]) => void – The function is called every time the value changes.
onComplete (value: string) => void – The function is called when all fields are filled in.
actionRef React.Ref<PinInputActions> – A reference to imperative actions.
autoFocus boolean false Automatic focus setting at the first mount, is set to the first field.
defaultValues string[] [”,”,”,”,”,”] In the case when the component is unmanaged, default values are set, where the number of values in the array is equal to the number of fields.
type ‘numeric’ or ‘alphanumeric’ ‘numeric’ Changes the type of keyboard display on mobile devices.
otp boolean false If true, then the attribute autocomplete=“one-time-code” is added, otherwise autocomplete=“off”.
placeholder string ‘○’ Placeholder for the input element.
disabled boolean false If true, the transmission of event handlers onChange, onBlur, onFocus and onKeyDown in the parameters of each field is prevented.
mask boolean false If true, then the attribute type="password" is set, otherwise type="text".
error boolean false If true, then the focus behavior on the fields changes.

Return

Prop Type Default Description
fields PinInputFieldProps[] – An array of objects with attributes.
isFocused boolean – Whether the focus was set on any field.
clear (options?: { focus?: boolean }) => void { focus: false } Sets the initial values of the fields. Removes focus by default. The parameter can be passed { focus: true } to set the focus on the first field.

PinInputFieldProps

Prop Type Descriptions
ref React.RefCallback Returns a callback function to register the field.
value string Returns the value of the field.
disabled boolean Returns the value passed by the disabled parameter.
autoComplete ‘one-time-code’ or ‘off’ Returns either one-time-code if the parameter otp: true was passed, otherwise off.
inputMode ‘text’ or ‘numeric’ Returns either text if the parameter type: 'alphanumeric' was passed, otherwise numeric.
type ‘text’ or ‘password’ Returns either password if the mask: true parameter was passed, or text.
placeholder string Returns the value passed by the placeholder parameter if there are no focused fields.
onBlur (event: React.FocusEvent) => void Returns the handler for the focus loss event if disabled: false.
onFocus (event: React.FocusEvent) => void Returns the handler for the focus appearance event if disabled: false.
onChange (event: React.ChangeEvent) => void Returns a handler for the field change event if disabled: false.
onKeyDown (event: React.ChangeEvent) => void Returns a handler for the keystroke event if disabled: false.

PinInputActions

Name Type Description
blur () => void Imperative function call to lose focus.
focus (index?: number) => void Imperative function call to set focus on the first empty field. In the case when error: true. the focus is set to the first empty field. The argument takes an optional parameter in the form of a number (ordinal index), which will set the focus on a specific field.

Example

import * as React from 'react'
import { usePinInput, PinInputActions } from 'react-pin-input-hook'

function Component() {
  const [values, setValues] = React.useState(['', '', '', '', '', ''])
  const [error, setError] = React.useState(false)
  const actionRef = React.useRef<PinInputActions>(null)
  const { fields } = usePinInput({
    values,
    onChange: setValues,
    error,
    actionRef,
  })

  const onSubmit = () => {
    // Check if there is at least one empty field. If there is, the input is considered empty.
    if (values.includes('')) {
      // Setting the error.
      setError(true)
      // We set the focus on the first empty field if `error: true` was passed as a parameter in `options`.
      actionRef.current?.focus()
    }
  }

  return (
    <form>
      <div className='pin-input'>
        {fields.map((propsField, index) => (
          <input key={index} className='pin-input__field' {...propsField} />
        ))}
      </div>
      <button onClick={onSubmit}>Submit</button>
    </form>
  )
}

GitHub

View Github