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.

Getting Started

Prerequisites

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.

Installation

NPM

npm install react-confirmation-code-input

Yarn

yarn add react-confirmation-code-input

PNPM

pnpm add react-confirmation-code-input

Usage

Usage utilizing the hook

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 (
    <main>
      <div className="input-container">
        {refs.map((ref, index) => (
          <input key={index} value={inputs[index]} ref={ref} {...inputProps} />
        ))}
      </div>
      <div className="button-box">
        <button onClick={onReset}>Reset</button>
        <button onClick={clear}>Clear</button>
        <button onClick={onSetFocus}>Focus</button>
      </div>
    </main>
  );
}

Using the provided Component

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<Handles>(null);
  const { reset, clear, setFocus } = React.useMemo(
    () => ({
      reset: () => handlesRef.current.reset(),
      clear: () => handlesRef.current.clear(),
      setFocus: () => handlesRef.current.setFocus(),
    }),
    []
  );

  return (
    <main>
      <ConfirmationCodeInput
        ref={handlesRef}
        length={5}
        allowedPattern="numeric"
        autoFocus
        initialValue="01234"
      />
      <div className="button-box">
        <button onClick={reset}>Reset</button>
        <button onClick={clear}>Clear</button>
        <button onClick={setFocus}>Focus</button>
      </div>
    </main>
  );
}

API

hook version

The hook takes an object as parameter and returns an object as a result:

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:

(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:

(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:

{
    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:

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

| Property | Description | Type | | ---------- | --------------------------------------------------------------------------------- | ------------------------------------ | | refs | An array of refs each of which needs to be passed to the respective input element | Array<RefObject<HTMLInputElement>> | | 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<HTMLInputElement> | | onKeyDown | onKeyDown event handler | KeyboardEventHandler<HTMLInputElement> | | onPaste | onPaste event handler | ClipboardEventHandler<HTMLInputElement> | | onInput | onInput event handler | FormEventHandler<HTMLInputElement> |

Component

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.

Contact

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