PIN Input

Allows users to input a sequence of one-character alphanumeric inputs.

	<script lang="ts">
  import { PinInput, type PinInputRootSnippetProps } from "bits-ui";
  import { toast } from "svelte-sonner";
  import { cn } from "$lib/utils/styles.js";
 
  let value = $state("");
 
  type CellProps = PinInputRootSnippetProps["cells"][0];
 
  function onComplete() {
    toast.success(`Completed with value ${value}`);
    value = "";
  }
</script>
 
<PinInput.Root
  bind:value
  class="group/pininput flex items-center text-foreground has-[:disabled]:opacity-30"
  maxlength={6}
  {onComplete}
>
  {#snippet children({ cells })}
    <div class="flex">
      {#each cells.slice(0, 3) as cell}
        {@render Cell(cell)}
      {/each}
    </div>
 
    <div class="flex w-10 items-center justify-center">
      <div class="h-1 w-3 rounded-full bg-border"></div>
    </div>
 
    <div class="flex">
      {#each cells.slice(3, 6) as cell}
        {@render Cell(cell)}
      {/each}
    </div>
  {/snippet}
</PinInput.Root>
 
{#snippet Cell(cell: CellProps)}
  <PinInput.Cell
    {cell}
    class={cn(
      // Custom class to override global focus styles
      "focus-override",
      "relative h-14 w-10 text-[2rem]",
      "flex items-center justify-center",
      "transition-all duration-75",
      "border-y border-r border-foreground/20 first:rounded-l-md first:border-l last:rounded-r-md",
      "text-foreground group-focus-within/pininput:border-foreground/40 group-hover/pininput:border-foreground/40",
      "outline outline-0",
      "data-[active]:outline-1 data-[active]:outline-white"
    )}
  >
    {#if cell.char !== null}
      <div>
        {cell.char}
      </div>
    {/if}
    {#if cell.hasFakeCaret}
      <div
        class="pointer-events-none absolute inset-0 flex animate-caret-blink items-center justify-center"
      >
        <div class="h-8 w-px bg-white"></div>
      </div>
    {/if}
  </PinInput.Cell>
{/snippet}

Overview

The PIN Input component provides a customizable solution for One-Time Password (OTP), Two-Factor Authentication (2FA), or Multi-Factor Authentication (MFA) input fields. Due to the lack of a native HTML element for these purposes, developers often resort to either basic input fields or custom implementations. This component offers a robust, accessible, and flexible alternative.

Key Features

  • Invisible Input Technique: Utilizes an invisible input element for seamless integration with form submissions and browser autofill functionality.
  • Customizable Appearance: Allows for custom designs while maintaining core functionality.
  • Accessibility: Ensures keyboard navigation and screen reader compatibility.
  • Flexible Configuration: Supports various PIN lengths and input types (numeric, alphanumeric).

Architecture

  1. Root Container: A relatively positioned root element that encapsulates the entire component.
  2. Invisible Input: A hidden input field that manages the actual value and interacts with the browser's built-in features.
  3. Visual Cells: Customizable elements representing each character of the PIN, rendered as siblings to the invisible input.

This structure allows for a seamless user experience while providing developers with full control over the visual representation.

Structure

	<script lang="ts">
	import { PinInput } from "bits-ui";
</script>
 
<PinInput.Root maxlength={6}>
	{#snippet children({ cells })}
		{#each cells as cell}
			<PinInput.Cell {cell} />
		{/each}
	{/snippet}
</PinInput.Root>

Managing Value State

Bits UI offers several approaches to manage and synchronize the component's value state, catering to different levels of control and integration needs.

1. Two-Way Binding

For seamless state synchronization, use Svelte's bind:value directive. This method automatically keeps your local state in sync with the component's internal state.

	<script lang="ts">
	import { PinInput } from "bits-ui";
	let myValue = $state("");
</script>
 
<button onclick={() => (myValue = "123456")}> Set value to 123456 </button>
 
<PinInput.Root bind:value={myValue}>
	<!-- -->
</PinInput.Root>

Key Benefits

  • Simplifies state management
  • Automatically updates myValue when the internal state changes (e.g., user typing in the input)
  • Allows external control (e.g., switching tabs via a separate button)

2. Change Handler

For more granular control or to perform additional logic on state changes, use the onValueChange prop. This approach is useful when you need to execute custom logic alongside state updates.

	<script lang="ts">
	import { PinInput } from "bits-ui";
	let myValue = $state("");
</script>
 
<PinInput.Root
	value={myValue}
	onValueChange={(v) => {
		myValue = v;
		// additional logic here.
	}}
>
	<!-- ... -->
</PinInput.Root>

Use Cases

  • Implementing custom behaviors on value change
  • Integrating with external state management solutions
  • Triggering side effects (e.g., logging, data fetching)

3. Fully Controlled

For complete control over the component's value state, use the controlledValue prop. This approach requires you to manually manage the value state, giving you full control over when and how the component responds to value change events.

To implement controlled state:

  1. Set the controlledValue prop to true on the PinInput.Root component.
  2. Provide a value prop to PinInput.Root, which should be a variable holding the current state.
  3. Implement an onValueChange handler to update the state when the internal state changes.
	<script lang="ts">
	import { PinInput } from "bits-ui";
	let myValue = $state("");
</script>
 
<PinInput.Root controlledValue value={myValue} onValueChange={(v) => (myValue = v)}>
	<!-- ... -->
</PinInput.Root>

When to Use

  • Implementing complex logic
  • Coordinating multiple UI elements
  • Debugging state-related issues

Paste Handling

The onPaste prop allows you to sanitize pasted text. This can be useful for cleaning up pasted text, like removing hyphens or other characters that should not make it into the input. This function should return the sanitized text.

	<script lang="ts">
	import { PinInput } from "bits-ui";
</script>
 
<PinInput.Root onPaste={(text) => text.replace(/-/g, "")}>
	<!-- ... -->
</PinInput.Root>

HTML Forms

The PinInput.Root component is designed to work seamlessly with HTML forms. Simply pass the name prop to the PinInput.Root component and the input will be submitted with the form.

Submit On Complete

To submit the form when the input is complete, you can use the onComplete prop.

	<script lang="ts">
	import { PinInput } from "bits-ui";
	let form = $state<HTMLFormElement>(null!);
</script>
 
<form method="POST" bind:this={form}>
	<PinInput.Root name="mfaCode" onComplete={() => form.submit()}>
		<!-- ... -->
	</PinInput.Root>
</form>

Patterns

You can use the pattern prop to restrict the characters that can be entered or pasted into the input.

Bits UI exports a few common patterns that you can import and use in your application.

  • REGEXP_ONLY_DIGITS - Only allow digits to be entered.
  • REGEXP_ONLY_CHARS - Only allow characters to be entered.
  • REGEXP_ONLY_DIGITS_AND_CHARS - Only allow digits and characters to be entered.
	<script lang="ts">
	import { PinInput, REGEXP_ONLY_DIGITS } from "bits-ui";
</script>
 
<PinInput.Root pattern={REGEXP_ONLY_DIGITS}>
	<!-- ... -->
</PinInput.Root>

API Reference

PINInput.Root

The pin input container component.

Property Type Description
value $bindable
string

The value of the input.

Default: undefined
onValueChange
function

A callback function that is called when the value of the input changes.

Default: undefined
controlledValue
boolean

Whether or not the value is controlled or not. If true, the component will not update the value state internally, instead it will call onValueChange when it would have otherwise, and it is up to you to update the value prop that is passed to the component.

Default: false
disabled
boolean

Whether or not the pin input is disabled.

Default: false
textalign
enum

Where is the text located within the input. Affects click-holding or long-press behavior

Default: 'left'
maxlength
number

The maximum length of the pin input.

Default: 6
onComplete
function

A callback function that is called when the input is completely filled.

Default: undefined
onPaste
function

A callback function that is called when the user pastes text into the input. It receives the pasted text as an argument and should return the sanitized text. Useful for cleaning up pasted text, like removing hyphens or other characters that should not make it into the input.

Default: undefined
inputId
string

Optionally provide an ID to apply to the hidden input element.

Default: undefined
pushPasswordManagerStrategy
enum

Enabled by default, it's an optional strategy for detecting Password Managers in the page and then shifting their badges to the right side, outside the input.

Default: undefined
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-pin-input-root
''

Present on the root element.

PINInput.Cell

A single cell of the pin input.

Property Type Description
cell
object

The cell object provided by the cells snippet prop from the PinInput.Root component.

Default: undefined
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See Child Snippet docs for more information.

Default: undefined
Data Attribute Value Description
data-active
''

Present when the cell is active.

data-inactive
''

Present when the cell is inactive.

data-pin-input-cell
''

Present on the cell element.