One-Time Password Input

Securely collect and validate numeric codes with automatic field navigation and keyboard support.

Two-step verification

A verification code has been sent to your email. Please enter the code below to verify this device.

This is a trusted device, don't ask again

import { type PropsOf, Slot, component$ } from "@builder.io/qwik";
import { Checkbox, Otp } from "@kunai-consulting/qwik";
import { LuCheck } from "@qwikest/icons/lucide";

export const MyDiv = component$((props: PropsOf<"div">) => {
  return (
    <div {...props}>
      <Slot />
    </div>
  );
});

export default component$(() => {
  const slots = Array.from({ length: 4 });

  return (
    <div class="flex flex-col items-center gap-4">
      <div class="max-w-80 flex flex-col items-center text-center">
        <InformationCircle class="*:stroke-qwik-blue-600" />
        <h2 class="py-4 text-lg font-semibold">Two-step verification</h2>
        <p class="text-sm">
          A verification code has been sent to your email. Please enter the code below to
          verify this device.
        </p>
      </div>

      <Otp.Root class="flex flex-col items-center justify-center">
        <Otp.HiddenInput />

        <div class="otp-container flex flex-row justify-center gap-2">
          {slots.map((slot) => (
            <Otp.Item
              key={`otp-item-${slot}`}
              class={
                "h-9 w-10 border-2 text-center rounded data-[highlighted]:ring-qwik-blue-800 data-[highlighted]:ring-[3px] caret-blue-600"
              }
            >
              <Otp.Caret class="text-blue-500 text-xl animate-blink-caret">|</Otp.Caret>
            </Otp.Item>
          ))}
        </div>
      </Otp.Root>

      <TrustedCheckbox />

      <button
        type="button"
        class="rounded-md bg-qwik-blue-700 px-4 py-2 text-white outline-qwik-blue-600"
      >
        Sign in securely
      </button>
    </div>
  );
});

const InformationCircle = component$((props: PropsOf<"svg">) => {
  return (
    <svg
      width="32"
      height="32"
      viewBox="0 0 32 32"
      fill="none"
      xmlns="http://www.w3.org/2000/svg"
      {...props}
    >
      <title>Information Circle</title>
      <path
        d="M17.3333 21.3333H16V16H14.6667M16 10.6667H16.0133M28 16C28 17.5759 27.6896 19.1363 27.0866 20.5922C26.4835 22.0481 25.5996 23.371 24.4853 24.4853C23.371 25.5996 22.0481 26.4835 20.5922 27.0866C19.1363 27.6896 17.5759 28 16 28C14.4242 28 12.8637 27.6896 11.4078 27.0866C9.95191 26.4835 8.62904 25.5996 7.51473 24.4853C6.40043 23.371 5.51652 22.0481 4.91346 20.5922C4.3104 19.1363 4.00002 17.5759 4.00002 16C4.00002 12.8174 5.2643 9.76516 7.51473 7.51472C9.76517 5.26428 12.8174 4 16 4C19.1826 4 22.2349 5.26428 24.4853 7.51472C26.7357 9.76516 28 12.8174 28 16Z"
        stroke="#2563EB"
        stroke-width="3"
        stroke-linecap="round"
        stroke-linejoin="round"
      />
    </svg>
  );
});

export const TrustedCheckbox = component$(() => {
  return (
    <Checkbox.Root>
      <Checkbox.HiddenInput />
      <div class="flex items-center gap-2">
        <Checkbox.Trigger
          class="size-[25px] rounded-lg relative bg-gray-500 
                     focus-visible:outline focus-visible:outline-1 focus-visible:outline-white
                     disabled:opacity-50 bg-qwik-neutral-200 data-[checked]:bg-qwik-blue-800 focus-visible:ring-[3px] ring-qwik-blue-600"
        >
          <Checkbox.Indicator
            class="data-[checked]:flex justify-center items-center absolute inset-0 
                      "
          >
            <LuCheck />
          </Checkbox.Indicator>
        </Checkbox.Trigger>
        <Checkbox.Label class="text-sm">
          This is a trusted device, don't ask again
        </Checkbox.Label>
      </div>
    </Checkbox.Root>
  );
});

Features

One-Time Password (OTP) input pattern
Auto-advance through fields when typing
Keyboard navigation with arrow keys
Selection management across multiple fields
Backspace navigation between fields
Input validation with custom patterns
Password manager compatibility
Focus and caret indication
Custom numeric input mode
Range selection support
Completion event handling
Value binding and control
Reactive disabled state
Individual item customization
Visual highlight state management

Anatomy

Part	Description
<Otp.Root>	Here's a comment for you!
<Otp.Item>	Individual item component for displaying a single OTP digit
<Otp.HiddenInput>	Hidden input component that handles OTP input interactions and validation
<Otp.Caret>	Component that renders a caret for OTP input focus indication

Examples

Basic Usage

The OTP input can be initialized with a default value using the value prop.

import { type PropsOf, component$ } from "@builder.io/qwik";
import type { DocumentHead } from "@builder.io/qwik-city";
import { Otp } from "@kunai-consulting/qwik";

export const head: DocumentHead = {
  title: "Qwik Design System",
  meta: [
    {
      name: "description",
      content: "Qwik Design System"
    }
  ]
};

export default component$(() => {
  return (
    <Otp.Root value="1234" class="flex flex-col items-center justify-center">
      <Otp.HiddenInput />

      <div class="otp-container flex flex-row justify-center gap-2">
        {Array.from({ length: 4 }, (_, index) => {
          const uniqueKey = `otp-${index}-${Date.now()}`;

          return (
            <Otp.Item
              key={uniqueKey}
              class={
                "h-9 w-10 border-2 text-center data-[highlighted]:border-blue-600 rounded data-[highlighted]:ring-blue-100  data-[highlighted]:ring-[3px] data-[highlighted]:pl-1 data-[highlighted]:pr-1 caret-blue-600"
              }
            >
              <Otp.Caret class="text-blue-500 text-xl animate-blink-caret">|</Otp.Caret>
            </Otp.Item>
          );
        })}
      </div>
    </Otp.Root>
  );
});

const InformationCircle = component$((props: PropsOf<"svg">) => {
  return (
    <svg
      width="32"
      height="32"
      viewBox="0 0 32 32"
      fill="none"
      xmlns="http://www.w3.org/2000/svg"
      {...props}
    >
      <title>Information Circle</title>
      <path
        d="M17.3333 21.3333H16V16H14.6667M16 10.6667H16.0133M28 16C28 17.5759 27.6896 19.1363 27.0866 20.5922C26.4835 22.0481 25.5996 23.371 24.4853 24.4853C23.371 25.5996 22.0481 26.4835 20.5922 27.0866C19.1363 27.6896 17.5759 28 16 28C14.4242 28 12.8637 27.6896 11.4078 27.0866C9.95191 26.4835 8.62904 25.5996 7.51473 24.4853C6.40043 23.371 5.51652 22.0481 4.91346 20.5922C4.3104 19.1363 4.00002 17.5759 4.00002 16C4.00002 12.8174 5.2643 9.76516 7.51473 7.51472C9.76517 5.26428 12.8174 4 16 4C19.1826 4 22.2349 5.26428 24.4853 7.51472C26.7357 9.76516 28 12.8174 28 16Z"
        stroke="#2563EB"
        stroke-width="3"
        stroke-linecap="round"
        stroke-linejoin="round"
      />
    </svg>
  );
});

This example demonstrates:

Using value prop to set an initial uncontrolled value
Default numeric validation pattern
Automatic field navigation

Visual Features

The OTP input can be disabled to prevent user interaction.

import { component$, useSignal } from "@builder.io/qwik";
import type { DocumentHead } from "@builder.io/qwik-city";
import { Otp } from "@kunai-consulting/qwik";

export const head: DocumentHead = {
  title: "Qwik Design System",
  meta: [
    {
      name: "description",
      content: "Qwik Design System"
    }
  ]
};

export default component$(() => {
  const isDisabled = useSignal(false);

  return (
    <>
      <Otp.Root
        disabled={isDisabled.value}
        class="flex flex-col items-center justify-center"
      >
        <Otp.HiddenInput />

        <div class="otp-container flex flex-row justify-center gap-2">
          {Array.from({ length: 4 }, (_, index) => {
            const uniqueKey = `otp-${index}-${Date.now()}`;

            return (
              <Otp.Item
                key={uniqueKey}
                class={
                  "h-9 w-10 border-2 text-center data-[highlighted]:border-blue-600 rounded data-[highlighted]:ring-blue-100  data-[highlighted]:ring-[3px] data-[highlighted]:pl-1 data-[highlighted]:pr-1 caret-blue-600 data-[disabled]:opacity-50"
                }
              >
                <Otp.Caret class="text-blue-500 text-xl animate-blink-caret">|</Otp.Caret>
              </Otp.Item>
            );
          })}
        </div>
      </Otp.Root>

      <button type="button" onClick$={() => (isDisabled.value = !isDisabled.value)}>
        Disable OTP
      </button>
    </>
  );
});

This example shows:

Using the disabled prop to control input state
Visual feedback for disabled state via data-disabled attribute

Advanced Usage

Controlled Input

The OTP input can be controlled using signals with bind:value.

import { component$, useSignal } from "@builder.io/qwik";
import type { DocumentHead } from "@builder.io/qwik-city";
import { Otp } from "@kunai-consulting/qwik";

export const head: DocumentHead = {
  title: "Qwik Design System",
  meta: [
    {
      name: "description",
      content: "Qwik Design System"
    }
  ]
};

export default component$(() => {
  const otpInput = useSignal<string>("");

  return (
    <>
      <Otp.Root bind:value={otpInput} class="flex flex-col items-center justify-center">
        <Otp.HiddenInput />

        <div class="otp-container flex flex-row justify-center gap-2">
          {Array.from({ length: 4 }, (_, index) => {
            const uniqueKey = `otp-${index}-${Date.now()}`;

            return (
              <Otp.Item
                key={uniqueKey}
                class={
                  "h-9 w-10 border-2 text-center data-[highlighted]:border-blue-600 rounded data-[highlighted]:ring-blue-100  data-[highlighted]:ring-[3px] data-[highlighted]:pl-1 data-[highlighted]:pr-1 caret-blue-600"
                }
              >
                <Otp.Caret class="text-blue-500 text-xl animate-blink-caret">|</Otp.Caret>
              </Otp.Item>
            );
          })}
        </div>
      </Otp.Root>
      <button type="button" onClick$={() => (otpInput.value = "1234")}>
        Change otp value
      </button>
    </>
  );
});

This example demonstrates:

Two-way binding with bind:value prop
Programmatic value updates
Reactive state management

Event Handling

The OTP input supports completion and change events.

import { $, component$, useSignal } from "@builder.io/qwik";
import type { DocumentHead } from "@builder.io/qwik-city";
import { Otp } from "@kunai-consulting/qwik";

export const head: DocumentHead = {
  title: "Qwik Design System",
  meta: [
    {
      name: "description",
      content: "Qwik Design System"
    }
  ]
};

export default component$(() => {
  const isDisabled = useSignal(false);

  const handleComplete = $(() => {
    isDisabled.value = true;
  });

  return (
    <>
      <Otp.Root
        disabled={isDisabled.value}
        onComplete$={handleComplete}
        class="flex flex-col items-center justify-center"
      >
        <Otp.HiddenInput />

        <div class="otp-container flex flex-row justify-center gap-2">
          {Array.from({ length: 4 }, (_, index) => {
            const uniqueKey = `otp-${index}-${Date.now()}`;

            return (
              <Otp.Item
                key={uniqueKey}
                class={
                  "h-9 w-10 border-2 text-center data-[highlighted]:border-blue-600 rounded data-[highlighted]:ring-blue-100  data-[highlighted]:ring-[3px] data-[highlighted]:pl-1 data-[highlighted]:pr-1 caret-blue-600 data-[disabled]:opacity-50"
                }
              >
                <Otp.Caret class="text-blue-500 text-xl animate-blink-caret">|</Otp.Caret>
              </Otp.Item>
            );
          })}
        </div>
      </Otp.Root>
    </>
  );
});

This example shows:

Using onComplete$ to handle filled state
Using onChange$ for value updates
Automatic validation and field progression

Change Events

Monitor input changes with the onChange$ handler.

import { $, component$, useSignal } from "@builder.io/qwik";
import type { DocumentHead } from "@builder.io/qwik-city";
import { Otp } from "@kunai-consulting/qwik";

export const head: DocumentHead = {
  title: "Qwik Design System",
  meta: [
    {
      name: "description",
      content: "Qwik Design System"
    }
  ]
};

export default component$(() => {
  const isChange = useSignal(false);

  return (
    <>
      <Otp.Root
        onChange$={$(() => {
          console.log("onChange$");
          isChange.value = true;
        })}
        class="flex flex-col items-center justify-center"
      >
        <Otp.HiddenInput />
        <div class="otp-container flex flex-row justify-center gap-2">
          {Array.from({ length: 4 }, (_, index) => {
            const uniqueKey = `otp-${index}-${Date.now()}`;

            return (
              <Otp.Item
                key={uniqueKey}
                class={
                  "h-9 w-10 border-2 text-center data-[highlighted]:border-blue-600 rounded data-[highlighted]:ring-blue-100  data-[highlighted]:ring-[3px] data-[highlighted]:pl-1 data-[highlighted]:pr-1 caret-blue-600"
                }
              >
                <Otp.Caret class="text-blue-500 text-xl animate-blink-caret">|</Otp.Caret>
              </Otp.Item>
            );
          })}
        </div>
      </Otp.Root>
      {isChange.value && <p>onChange$</p>}
    </>
  );
});

This example demonstrates:

Real-time value change detection
Event handling for input modifications
Integration with external state

Component State

Using Component State

The OTP component provides several ways to control its state through props:

Initial Value As shown in the initial example above, you can set an initial uncontrolled value using the value prop on <Otp.Root />:

<Otp.Root value="1234">
  {/* OTP items */}
</Otp.Root>

Controlled Value For controlled state management, use the bind:value prop as demonstrated in the reactive example above. This allows you to programmatically update the OTP value.
Disabled State The disabled example shows how to disable the entire OTP input using the disabled prop:

<Otp.Root disabled={true}>
  {/* OTP items */}
</Otp.Root>

State Interactions

Change Events As shown in the change example, use the onChange$ prop to listen for value changes:

<Otp.Root 
  onChange$={(value) => {
    // Handle value change
  }}
>
  {/* OTP items */}
</Otp.Root>

Completion Events The complete example demonstrates using onComplete$ to handle when all OTP digits are filled:

<Otp.Root
  onComplete$={() => {
    // Handle OTP completion
  }}
>
  {/* OTP items */}
</Otp.Root>

Password Manager Integration Control password manager suggestion positioning with the shiftPWManagers prop (enabled by default):

<Otp.Root shiftPWManagers={false}>
  {/* OTP items */}
</Otp.Root>

The component maintains internal state for:

Current input value
Focus state
Selection range
Current input position
Validation state These states are automatically managed based on user interaction and the provided props.

Based on the provided examples and API documentation, I'll document the configuration options for the OTP component.

Core Configuration

Input Pattern

By default, the OTP component only accepts numeric input (0-9). You can customize the input validation pattern through the pattern prop on <Otp.HiddenInput />. The default pattern is ^[0-9]*$.

Initial Value

The OTP component supports setting an initial uncontrolled value. As shown in the initial example above, you can pass the value prop to <Otp.Root /> to set the initial value.

Password Manager Integration

The OTP component includes built-in support for password managers. By default, password manager suggestions are shifted to the right of the OTP input. This behavior can be controlled via the shiftPWManagers prop on <Otp.Root />:

<Otp.Root shiftPWManagers={false}>
  {/* ... */}
</Otp.Root>

Input Length

The number of OTP digits is determined by the number of <Otp.Item /> components rendered. The component automatically manages the maximum input length based on this count.

Advanced Configuration

Value Binding

For reactive control over the OTP value, the component supports value binding through the bind:value prop. As shown in the reactive example above, this allows two-way binding with a signal.

Completion Handling

The component provides completion detection through the onComplete$ prop. As demonstrated in the complete example above, this handler is called when all OTP digits are filled.

Change Detection

For granular control over value changes, use the onChange$ prop. As shown in the change example above, this handler is called on every value change, receiving the current OTP value as an argument.

Disabled State

The entire OTP input can be disabled through the disabled prop on <Otp.Root />. As shown in the disabled example above, this affects all child components and prevents user interaction.

Note: The disabled state is reflected through the data-disabled attribute on both root and individual items, allowing for consistent styling across states.

API Reference

Otp Root

Inherits from: <div />

Props

Prop	Type	Default
"bind:value"	Signal<string>	-
_numItems	number	-
autoComplete	HTMLInputAutocompleteAttribute	-
onComplete$	QRL<() => void>	-
onChange$	QRL<(value: string) => void>	-
value	string	-
disabled	boolean	false
shiftPWManagers	boolean	true

Data Attributes

Attribute	Description
data-disabled	Indicates if the entire OTP input is disabled

Otp Item

Inherits from: <div />

Props

Prop	Type	Default	Description
_index	number	0
index	number	-

Data Attributes

Attribute	Description
data-highlighted	Indicates if the OTP item is currently highlighted
data-disabled	Indicates if the OTP item is disabled

Otp Hidden Input

Inherits from: <input />

Props

Prop	Type	Default	Description
pattern	string \| null	-

Data Attributes

Attribute	Description
data-shift	Indicates whether password manager suggestions should be shifted

Otp Caret

Inherits from: <span />

Accessibility

Keyboard Interactions

Key	Description
ArrowLeft	When focus is on the hidden input, moves focus to the previous OTP item. Prevents skipping over filled slots when moving from empty slots
ArrowRight	When focus is on the hidden input, moves focus to the next OTP item
Backspace	When focus is on the hidden input, deletes the previous character and moves focus backwards
0-9	When focus is on the hidden input, enters a numeric digit and moves focus to the next item
Shift	When held down, allows range selection of multiple OTP items using arrow keys
Tab	Moves focus into and out of the OTP input component
Any non-numeric	When focus is on the hidden input, input is prevented if it doesn't match the pattern (defaults to numbers only)