@svipwrap/react-confirmation-code-input

About The Project

This library provides a hook that lets you write a confirmation code input component while the library manages the refs and some interactions like focusing the next input element when an input has been entered. It can thus be considered headless.

The library also provides you with a component implemented on top of that hook. It lets you override the input and container elements' styling by passing respective class names of your choice as properties to the component.

(back to top)

Getting Started

$3

This is a react library primarily providing a headles react hook for you to implement your own confirmation code input whilst delegating the handling of the element refs and some of the behaviour to said hook. You therefore need a react version as a peer dependency that has support for hooks i.e. any version of react >= 16.8.

$3

#### NPM

npm install react-confirmation-code-input

#### Yarn

yarn add react-confirmation-code-input

#### PNPM

pnpm add react-confirmation-code-input

(back to top)

Usage

$3

``typescript
import * as React from "react";
import { useConfirmationCodeInput } from "react-confirmation-code-input";
import "./style.css";

export default function App() {
const {
refs,
value: inputs,
clear,
setFocus,
reset,
inputProps,
} = useConfirmationCodeInput({
length: 5,
allowedPattern: "numeric",
initialValue: "01234",
autoFocus: true,
});

// reset and setFocus take optional params so we can't pass them directly
// to onClick but have to eliminate the optional parameter first
const onReset = React.useCallback(() => reset(), []);
const onSetFocus = React.useCallback(() => setFocus(), []);

return (


`typescript
import * as React from "react";
import {
ConfirmationCodeInput,
ConfirmationCodeInputHandles as Handles,
} from "react-confirmation-code-input";
import "./style.css";

export default function App() {
const handlesRef = React.useRef(null);
const { reset, clear, setFocus } = React.useMemo(
() => ({
reset: () => handlesRef.current.reset(),
clear: () => handlesRef.current.clear(),
setFocus: () => handlesRef.current.setFocus(),
}),
[]
);

return (


`ts
useConfirmationCodeInput(options: UseConfirmationCodeInputProps) => UseConfirmationCodeInputResult
`

#### UseConfirmationCodeInputProps:

allowedPattern?: AllowedPattern;
autoFocus?: boolean;
useValueHook?: UseValue;
initialValue?: string;
length: number;
onChange?: (value: string) => void;

| Parameter | Description | Type | Required | Default |
| -------------- | ------------------------------------------------ | ----------------------- | -------- | --------- |
| allowedPattern | Accepted pattern | AllowedPattern | no | "numeric" |
| useValueHook | The hook to store and modify the input value | UseValue | no | |
| autoFocus | wheter to put focus on first input upon mounting | boolean | no | true |
| initialValue | Initial value as string | string | no | |
| length | Number of individual inputs | number | yes | |
| onChange | method called when the value changes | (value: string) => void | no | |

#### AllowedPattern:

Allowed Pattern is either one of the predefined patterns "numeric" | "alpha" | "alphanumeric", a RegExp or a function with the following signature:

`ts
(input: string, index: number, value: string[]) => boolean;
`

#### UseValue

Only provide this if you want to intercept/modify the input or the way it is stored. The signature is as follows:

`ts
(options: UseValueOptions) => [string[], Mutators];
`

UseValueOptions and Mutators are described below. You need to provide the same signature if you want to pass in a custom useValue parameter.

#### UseValueOptions:

An object of the shape { allowedPattern: AllowedPattern, length: number }:

| Property | Description |
| -------------- | ---------------------------- |
| allowedPattern | The pattern for valid inputs |
| length | The length of a valid code |

#### Mutators:

An object of the shape:

`ts
{
clear: () => void;
reset: (value?: string) => void;
update: (input: string, index: number, options: UpdateOptions) => void;
}

`

| Property | Description | Type |
| -------- | --------------------------------------------------------- | ---------------------------------------------------------------- |
| clear | A method to clear the value | () => void |
| reset | A method to reset the value to either the given value | (value?: string) => void |
| update | A method to update the value upon a given input character | (input: string, index: number, options: UpdateOptions) => void |

#### UseConfirmationCodeInputResult:

The result of calling useConfirmationCodeInput is an option adhering to the following interface:

`ts
refs: Array>;
value: string[];
reset: (value?: string) => void;
clear: () => void;
setFocus: (index?: number) => void;
inputProps: {
onFocus: FocusEventHandler;
onKeyDown: KeyboardEventHandler;
onPaste: ClipboardEventHandler;
onInput: FormEventHandler;
};
`

| Property | Description | Type |
| ---------- | --------------------------------------------------------------------------------- | ------------------------------------ |
| refs | An array of refs each of which needs to be passed to the respective input element | Array> |
| value | The current value as a string array with each value comprising a single character | string[] |
| reset | see Mutators | (value?: string) => void |
| clear | see Mutators | () => void |
| setFocus | see Mutators | (index?: number) => void |
| inputProps | The object with properties that must be passed to each individual input | InputProps |

#### InputProps

The inputProps returned by the useConfirmationCodeInputResult hook are supposed to be spread into each of the input elements. They comprise needed event handlers on which the hook relies in order to react to user events.

| Property | Description | Type |
| --------- | ----------------------- | ----------------------------------------- |
| onFocus | onFocus event handler | FocusEventHandler |
| onKeyDown | onKeyDown event handler | KeyboardEventHandler |
| onPaste | onPaste event handler | ClipboardEventHandler |
| onInput | onInput event handler | FormEventHandler |

$3

The component takes the following parameters:

| Property | Description | Type | Required | Default |
| -------------- | ------------------------------------------------------------- | ---------------------------------------------------- | -------- | --------- |
| ref | reference to get access to the exposed Mutators | React.MutableRefObject | no | |
| length | See corresponding hook param | number | yes | |
| allowedPattern | See corresponding hook param | AllowedPattern | no | numeric |
| initialValue | See corresponding hook param | string | no | |
| onChange | See corresponding hook param | (value: string) => void | no | |
| autoFocus | See corresponding hook param | boolean | no | |
| containerCls | CSS class to be appended to the input container's class names | string | no | |
| inputCls | CSS class to be appended to the input's class names | string | no | |
| disabled | Whether the inputs are disabled | boolean | no | |
| isPassword | Whether the inputs are of type password | boolean | no | |
| inputMode | change the appearance of the keyboard | InputMode | no | numeric |

License

Distributed under the MIT License. See LICENSE` for more information.

(back to top)

Contact

Project Link: https://github.com/SSzzPP/svipwrap-react-confirmation-code-input

(back to top)

[contributors-shield]: https://img.shields.io/github/contributors/SSzzPP/svipwrap-react-confirmation-code-input.svg?style=for-the-badge
[contributors-url]: https://github.com/SSzzPP/svipwrap-react-confirmation-code-input/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/SSzzPP/svipwrap-react-confirmation-code-input.svg?style=for-the-badge
[forks-url]: https://github.com/SSzzPP/svipwrap-react-confirmation-code-input/network/members
[stars-shield]: https://img.shields.io/github/stars/SSzzPP/svipwrap-react-confirmation-code-input.svg?style=for-the-badge
[stars-url]: https://github.com/SSzzPP/svipwrap-react-confirmation-code-input/stargazers
[issues-shield]: https://img.shields.io/github/issues/SSzzPP/svipwrap-react-confirmation-code-input.svg?style=for-the-badge
[issues-url]: https://github.com/SSzzPP/svipwrap-react-confirmation-code-input/issues
[license-shield]: https://img.shields.io/github/license/SSzzPP/svipwrap-react-confirmation-code-input.svg?style=for-the-badge
[license-url]: https://github.com/SSzzPP/svipwrap-react-confirmation-code-input/blob/master/LICENSE.txt
[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB
[React-url]: https://reactjs.org/