react-pin-field
Version:
React component for entering PIN codes
130 lines (83 loc) • 7.28 kB
Markdown
# 📟 React PIN Field [](https://github.com/soywod/react-pin-field/actions/workflows/tests.yml) [](https://app.codecov.io/gh/soywod/react-pin-field) [](https://www.npmjs.com/package/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`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) left-to-right and right-to-left
- Supports HTML [`autofocus`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) by focusing either the first or the last input, depending on `dir`
- Supports [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) attributes like `aria-required`, `aria-label`…
- Supports [key composition](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event)
## Installation
```
npm install react-pin-field
```
## Usage
```typescript
import PinField from "react-pin-field";
```
### Props
```typescript
// 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`:
```tsx
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](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components) 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:
```tsx
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](https://soywod.github.io/react-pin-field/?path=/story/pinfield--controlled).*
## Contributing
*See the [Contributing guide](./CONTRIBUTING.md).*
## Sponsoring
If you appreciate the project, feel free to donate using one of the following providers:
[](https://github.com/sponsors/soywod)
[](https://ko-fi.com/soywod)
[](https://www.buymeacoffee.com/soywod)
[](https://liberapay.com/soywod)
[](https://thanks.dev/soywod)
[](https://www.paypal.com/paypalme/soywod)