Pin Input

A row of boxes for entering a short code, one character each, such as a sign-in code.

Usage

Code
import { PinInput } from '@leverui/components';
Code
<PinInput.Root count={4}>
  <PinInput.HiddenInput />
  <PinInput.Control>
    <PinInput.Input />
  </PinInput.Control>
</PinInput.Root>

For one ready-made component, see the snippet below.

Examples

Sizes

Pass the size prop to the PinInput.Root component to change the size of the pin input component

One time code

Pass the otp prop to the PinInput.Root component to make the pin input component behave like a one-time code input. This helps improve the user experience when entering OTP codes

Auto Submit

Use the autoSubmit prop to submit the owning form automatically when every input has been filled.

The form submits when all digits are entered.

Sanitize Pasted Values

Use the normalizeValue prop to remove formatting such as dashes or spaces from pasted values before validation.

1-2-3-4
Dashes are removed before validation.

Mask

Pass the mask prop to the PinInput.Root component to obscure the entered pin code

Placeholder

Pass the placeholder prop to the PinInput.Root component to add a placeholder to the pin input

Field

Here's an example of how to compose the Field and the PinInput components

Hook Form

Here's an example of how to compose the Field and the PinInput components in a Solid form with signal-based validation

Controlled

Pass the value and onValueChange props to the PinInput.Root component to control the value of the pin input

Store

An alternative way to control the pin input is to use the RootProvider component and the usePinInput store hook. This way you can access the pin input state and methods from outside the component.

Attached

Pass the attached prop to the PinInput.Root component to attach the pin input to the input field

With separator

Wrap each segment in Group with attached, add a separator between segments in PinInput.Control, and set count on PinInput.Root to the input count.

–

Alphanumeric

Pass the type prop to the PinInput.Root component to allow the user to enter alphanumeric characters. Values can be either alphanumeric, numeric, or alphabetic

Closed Component

Code
import { For, omit } from 'solid-js';
import type { JSX } from '@solidjs/web';
import { Group, PinInput as PinInputParts, type PinInputRootBaseProps } from '@leverui/components';

export type PinInputProps = Omit<PinInputRootBaseProps, 'attached'> & {
  count?: number;
  inputProps?: JSX.InputHTMLAttributes<HTMLInputElement>;
  attached?: boolean;
};

export function PinInput(props: PinInputProps) {
  const rest = omit(props, 'count', 'inputProps', 'attached');
  const indexes = () => Array.from({ length: props.count ?? 4 }, (_, index) => index);

  return (
    <PinInputParts.Root count={props.count ?? 4} {...rest}>
      <PinInputParts.HiddenInput {...props.inputProps} />
      <PinInputParts.Control>
        <Group attached={props.attached}>
          <For each={indexes()}>{(index) => <PinInputParts.Input index={index} />}</For>
        </Group>
      </PinInputParts.Control>
    </PinInputParts.Root>
  );
}

Usage

Code
<PinInput mask />

Props

Root

PropDefaultTypeDescription
placeholder'○'stringPlaceholder in each input.
type'numeric''numeric' | 'alphanumeric' | 'alphabetic'Characters the pin input accepts.
colorPalette'gray'stringColor palette.
size'md''2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'Input size.
variant'outline''outline' | 'subtle' | 'flushed'Input style.
as—'div'HTML tag to render.
asChild—Solid render functionRender your own element with the root's props.
unstyled—booleanTurn off the default styles.
autoFocus—booleanFocus the first input when the pin input appears.
autoSubmit—booleanSubmit the form once every input is filled.
blurOnComplete—booleanRemove focus once the code is complete.
count—numberNumber of inputs. Lets the server render correct ARIA attributes.
defaultValue—string[]Starting value.
disabled—booleanDisable the inputs.
form—stringForm the underlying input belongs to.
id—stringUnique id.
ids—Element ID mapIds of the elements inside.
invalid—booleanMark the pin input as invalid.
mask—booleanHide typed characters, like type=password.
name—stringInput name, for sending the value with a form.
onValueChange—(details: ValueChangeDetails) => voidCalled when the value changes.
onValueComplete—(details: ValueChangeDetails) => voidCalled when every input has a valid value.
onValueInvalid—(details: ValueInvalidDetails) => voidCalled when an invalid value is entered.
otp—booleanUse autocomplete="one-time-code" on the inputs.
pattern—stringRegular expression the typed value is checked against.
readOnly—booleanMake the pin input read-only.
required—booleanMark the pin input as required.
normalizeValue—(value: string) => stringClean a pasted value before it is checked.
selectOnFocus—booleanSelect an input's value when it gets focus.
translations—IntlTranslationsTranslated labels for assistive technology.
value—string[]Value, when you control it.
attached—boolean or responsive objectJoin the inputs into one group.

Each visible Input needs its own index, counting from 0. Set count so the server renders the correct accessible labels. Add HiddenInput to send the value with a form. The value is an array of strings.

size, variant, and attached take a value per breakpoint: base, sm, md, lg, xl, and 2xl. Pass an object, or an array that may skip breakpoints.

readOnly works on the root or on a Field.Root around it. PinInput.PropsProvider sets default props for the roots inside it. A prop on a root wins. To control the pin input from outside, call usePinInput({ count }) inside a Solid owner and pass the accessor to PinInput.RootProvider.

Customize with CSS

Load the Lever UI stylesheet first. The class names are stable.

Code
.leverui-pin-input__input {
  border-color: rebeccapurple;
}

The root, label, control, and input each have a .leverui-pin-input__* class. Each visible input also has .leverui-input, so it gets the Input component's styles. Set the --leverui-* variables on a parent, or target a part class.

Code
.verification-code {
  --leverui-colors-border: rebeccapurple;
}

.verification-code .leverui-pin-input__input {
  background: lavender;
}

Use class and style for one-off changes. unstyled on the root or on a part turns off its default styles.

Explorer

Click a part name in the sidebar to highlight it in the preview.

Component Anatomy

Hover to highlight, click to select parts