react-pin-field

The PinField component accepts a combination of standard HTML input attributes and specialized props for managing PIN entry.

Native Props

PinField inherits from InputHTMLAttributes<HTMLInputElement>, but the following props are omitted and replaced by the library's internal logic to ensure correct PIN handling:

• onChange
• onKeyDown
• onCompositionStart
• onCompositionEnd

By default, the component uses type="text", inputMode="text", autoCapitalize="off", autoCorrect="off", and autoComplete="off" to prevent unexpected browser behavior during PIN entry.

PinField Specific Props

These props control the behavior and accessibility of the PIN field:

• length (number): The required number of characters in the PIN. Defaults to 5.
• format (function): A function (char: string) => string used to transform each character as it is entered.
• formatAriaLabel (function): A function (index: number, total: number) => string used to generate accessibility labels for each digit. Defaults to `PIN field ${index} of ${total}`.
• onChange (function): A callback (value: string) => void triggered whenever the PIN value changes.
• onComplete (function): A callback (value: string) => void triggered when the PIN reaches the specified length.
• handler (Handler): An optional custom handler for managing the PIN logic.

The PinField component is the primary UI element for rendering a series of input fields for PIN entry. It renders a collection of individual <input> elements, one for each character in the PIN. It supports custom formatting, length configuration, and provides lifecycle callbacks for changes and completion.

Key features:

• Automatic Focus Management: Handles moving focus between inputs as the user types.
• RTL Support: Automatically reverses the input order if the dir prop is set to rtl.
• Accessibility: Uses formatAriaLabel to provide meaningful labels for each input field.
• Ref Forwarding: The component forwards a ref that resolves to an array of HTMLInputElements, allowing direct access to the underlying DOM nodes.

import { PinField } from 'react-pin-field';

function MyComponent() {
  return (
    <PinField 
      length={4} 
      onChange={(value) => console.log('Current PIN:', value)}
      onComplete={(value) => console.log('PIN completed:', value)}
    />
  );
}

The usePinField hook provides the core logic and state management for a PIN input field. It returns a Handler object containing everything needed to synchronize multiple input elements with a single PIN value.

To use it, call usePinField() and destructure the returned properties. You will typically use refs to attach to your individual input elements, state to determine the status of each digit (like focus or error), and value to get the current full PIN string.

Returned Handler Object

Example Usage

import { usePinField } from 'react-pin-field';

function MyPinComponent() {
  const { refs, state, value, setValue } = usePinField();

  return (
    <div>
      <div style={{ display: 'flex', gap: '8px' }}>
        {/* Create an input for each digit in the state length */}
        {Array.from({ length: state.length }).map((_, index) => (
          <input
            key={index}
            ref={(el) => (refs.current[index] = el!)}
            value={state.values[index] || ''}
            // ... other input props
          />
        ))}
      </div>
      <p>Current PIN: {value}</p>
    </div>
  );
}