3.1.5 • Published 3 months ago

react-pin-field v3.1.5

Weekly downloads
1,980
License
MIT
Repository
github
Last release
3 months ago

📟 React PIN Field tests codecov npm

React component for entering PIN codes.

gif

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

Installation

yarn add react-pin-field
# or
npm install react-pin-field

Usage

import PinField from "react-pin-field";

Props

type PinFieldProps = {
  ref?: React.Ref<HTMLInputElement[]>;
  className?: string;
  length?: number;
  validate?: string | string[] | RegExp | ((key: string) => boolean);
  format?: (char: string) => string;
  onResolveKey?: (key: string, ref?: HTMLInputElement) => any;
  onRejectKey?: (key: string, ref?: HTMLInputElement) => any;
  onChange?: (code: string) => void;
  onComplete?: (code: string) => void;
  style?: React.CSSProperties;
} & React.InputHTMLAttributes<HTMLInputElement>;

const defaultProps = {
  ref: {current: []},
  className: "",
  length: 5,
  validate: /^[a-zA-Z0-9]$/,
  format: key => key,
  formatAriaLabel: (idx, length) => `pin code ${idx} of ${length}`,
  onResolveKey: () => {},
  onRejectKey: () => {},
  onChange: () => {},
  onComplete: () => {},
  style: {},
};

Reference

Every input can be controlled thanks to the React reference:

<PinField ref={ref} />;

// reset all inputs
ref.current.forEach(input => (input.value = ""));

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

Style

The 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

Length

Length of the code (number of characters).

Validate

Characters can be validated with a validator. A validator can take the form of:

  • a String of allowed characters: abcABC123
  • an Array of allowed characters: ["a", "b", "c", "1", "2", "3"]
  • a RegExp: /^[a-zA-Z0-9]$/
  • a predicate: (char: string) => boolean

Format

Characters can be formatted with a formatter (char: string) => string.

Format Aria Label(s)

This function is used to generate accessible labels for each input within the <PinField />. By default it renders the string pin code 1 of 6, pin code 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.

Events

  • onResolveKey: when a key passes the validator
  • onRejectKey: when a key is rejected by the validator
  • onChange: when the code changes
  • onComplete: when the code has been fully filled

Examples

See the live demo.

Development

git clone https://github.com/soywod/react-pin-field.git
cd react-pin-field
yarn install

To start the development server:

yarn start

To build the lib:

yarn build

To build the demo:

yarn build:demo

Tests

Unit tests

Unit tests are handled by Jest (.test files) and Enzyme (.spec files).

yarn test:unit

End-to-end tests

End-to-end tests are handled by Cypress (.e2e files).

yarn start
yarn test:e2e

Sponsoring

github paypal ko-fi buy-me-a-coffee liberapay

3.1.5

3 months ago

3.1.4

7 months ago

3.1.3

1 year ago

3.1.2

1 year ago

3.1.1

1 year ago

3.1.0

1 year ago

3.0.9

2 years ago

3.0.12

2 years ago

3.0.13

2 years ago

3.0.10

2 years ago

3.0.11

2 years ago

3.0.16

2 years ago

3.0.7

2 years ago

3.0.14

2 years ago

3.0.6

2 years ago

3.0.15

2 years ago

2.0.0-beta.3

2 years ago

2.0.0-beta.2

3 years ago

2.0.0-beta.1

3 years ago

2.0.0-beta.0

3 years ago

1.1.0

3 years ago

1.0.6

3 years ago

1.0.5

3 years ago

1.0.4

4 years ago

1.0.3

4 years ago

1.0.2

4 years ago

1.0.1

4 years ago

1.0.0

4 years ago

0.3.1

4 years ago

0.3.0

4 years ago

0.2.7

4 years ago

0.2.6

4 years ago

0.2.5

4 years ago

0.2.3

4 years ago

0.2.4

4 years ago

0.2.1

4 years ago

0.2.2

4 years ago

0.2.0

4 years ago

0.1.8

4 years ago

0.1.7

4 years ago

0.1.6

4 years ago

0.1.5

4 years ago

0.1.4

4 years ago

0.1.3

4 years ago

0.1.2

4 years ago

0.1.1

4 years ago

0.1.0

4 years ago