react-pin-field

📟 React PIN Field

React component for entering PIN codes

Live demo available at https://soywod.github.io/react-pin-field/.

Features

• Written in TypeScript, tested with Jest and Cypress
• Relies on onchange native event with minimum interaction for better browser compatibility
• Supports HTML dir left-to-right and right-to-left
• Supports HTML autofocus by focusing either the first or the last input, depending on dir
• Supports ARIA attributes like aria-required, aria-label…
• Supports key composition

Installation

npm install react-pin-field

Usage

import PinField from "react-pin-field";

Props

// React PIN Field inherits native props from HTMLInputElement,
// except few event handlers that are overriden:
type NativeProps = Omit<
  InputHTMLAttributes<HTMLInputElement>,
  "onChange" | "onKeyDown" | "onCompositionStart" | "onCompositionEnd"
>;

type Props = NativeProps & {
  length?: number;
  format?: (char: string) => string;
  formatAriaLabel?: (index: number, total: number) => string;
  onChange?: (value: string) => void;
  onComplete?: (value: string) => void;  
};

length

The length of the PIN field, which represents the number of inputs.

Defaults to 5

format

Characters can be formatted with any function of type (char: string) => string.

Defaults to identity function char => char

formatAriaLabel

This function is used to generate accessible labels for each input within the <PinField />. By default it renders the string PIN field 1 of 6, PIN field 2 of 6, etc., depending on the actual index of the input field and the total length of the pin field.

You can customize the aria-label string by passing your own function. This can be useful for: i) site internationalisation (i18n); ii) simply describing each input with different semantics than the ones provided by react-pin-field.

Defaults to (n, total) => "PIN field ${n} of ${total}"

onChange

This function is called everytime the PIN field changes its value.

onComplete

This function is called everytime the PIN field is completed. A PIN field is considered complete when:

• Every input has a defined value
• Every input passed the standard HTML validation (required, pattern etc)

Reference

React PIN Field exposes a special reference which is an array of HTMLInputElement:

const ref = useRef<HTMLInputElement[]>();

<PinField ref={ref} />;

// focus the third input
ref.current[2].focus();

Style

React PIN Field can be styled either with style or className. This last one allows you to use pseudo-classes like :nth-of-type, :focus, :hover, :valid, :invalid…

Hook

By default, React PIN Field is an uncontrolled component, which means that its internal state cannot be changed. You can only listen to changes via onChange and onComplete.

To control the React PIN Field state, you can use the usePinField() custom hook:

const handler = usePinField();

// The handler exposes a value and setValue to control the PIN code,
// as well as a state and dispatch for advanced usage.

// Let know the PIN field that you want to use this custom state
// instead of its internal one.
return <PinField handler={handler} />

See the controlled section of the live demo.

Contributing

See the Contributing guide.

Sponsoring

If you appreciate the project, feel free to donate using one of the following providers: