Skip to content

Latest commit

 

History

History
343 lines (262 loc) · 14.1 KB

README.md

File metadata and controls

343 lines (262 loc) · 14.1 KB
Raw

Contributors Forks Stargazers Issues MIT License


React Confirmation Code Input

React hook and component for integrating a confirmation code input into your application
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. License
  5. Contact

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

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

(back to top)

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>
  );
}

Open in StackBlitz

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>
  );
}

Open in StackBlitz

(back to top)

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

License

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

(back to top)

Contact

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

(back to top)