ondraa96 / react-pin-input-hook

React hook for entering a PIN code

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((fieldProps, index) => (
        <input key={index} className='pin-input__field' {...fieldProps} />
      ))}
    </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((fieldProps, index) => (
        <input key={index} className='pin-input__field' {...fieldProps} />
      ))}
    </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.KeyboardEvent) => 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((fieldProps, index) => (
          <input key={index} className='pin-input__field' {...fieldProps} />
        ))}
      </div>
      <button onClick={onSubmit}>Submit</button>
    </form>
  )
}