otp grid

A lightweight and customizable React OTP input component for building verification flows such as login OTP, email verification, and 2FA.

otp-grid provides a simple, controlled OTP input with features like auto focus navigation, paste support, and keyboard handling while allowing developers full control over state.

✨ Features

• 🔢 Numeric OTP input validation
• ⌨️ Smart keyboard navigation
• ⬅️ Backspace moves to previous input
• 📋 Paste full OTP support
• 🎯 Auto focus to next input
• 🎨 Customizable styling
• ⚡ Lightweight and dependency-free
• 🧩 Fully controlled component

📦 Installation

npm install otp-grid

🚀 Basic Usage

"use client";
import { useState } from "react";
import OtpBox from "otp-grid";

export default function Example() {
  const [otp, setOtp] = useState(Array(6).fill(""));

  return (
    <div>
      <OtpBox length={6} otp={otp} setOtp={setOtp} />

      <button onClick={() => console.log(otp.join(""))}>
        Verify OTP
      </button>
    </div>
  );
}

⚙️ Props

| Prop | Type | Default | Description | | -------- | ------------------------------------ | -------- | ---------------------------------------- | | length | number | 6 | Number of OTP input fields | | theme | string | "gray" | Custom Tailwind or CSS class for styling | | otp | string[] | required | OTP state array | | setOtp | Dispatch<SetStateAction<string[]>> | required | State setter for updating OTP |

🎨 Styling

You can customize the input appearance using the theme prop.

Example with Tailwind:

<OtpBox
  length={4}
  theme="border-amber-500 focus:ring-amber-500"
  otp={otp}
  setOtp={setOtp}
/>

Default input styles:

• Center aligned text
• Fixed width and height
• Focus ring support

📋 Paste Support

Users can paste the full OTP directly into the first input.

Example:

123456

The component will automatically distribute the digits across all input fields.

⌨️ Keyboard Behavior

| Key | Behavior | | ----------- | ---------------------------------------- | | Number keys | Fill current input | | Backspace | Clears input and moves to previous field | | Paste | Automatically fills OTP inputs |

🧠 Controlled Component Pattern

otp-grid is a controlled component, meaning the OTP state is managed by your application.

Example:

const [otp, setOtp] = useState(Array(6).fill(""));

To retrieve the OTP:

const finalOtp = otp.join("");

📂 Example UI

Typical OTP layout:

[ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ]

Used commonly for:

• Login verification
• Phone number verification
• Two-factor authentication (2FA)
• Email confirmation

🛠 Example with Enter Submit

useEffect(() => {
  const handleKey = (e: KeyboardEvent) => {
    if (e.key === "Enter") {
      console.log(otp.join(""));
    }
  };

  window.addEventListener("keydown", handleKey);

  return () => window.removeEventListener("keydown", handleKey);
}, [otp]);

🧩 Built With

• React
• TypeScript
• Tailwind CSS compatible

📄 License

MIT

⭐ Contributing

Contributions, issues, and feature requests are welcome!

If you like this package, consider starring the repository ⭐

👨‍💻 Author

Created by Someswar Gorai