Input

Input with a spring-animated caret.

Installation

npx shadcn@latest add @iconiq/input

File Structure

Usage

"use client";

import { useState } from "react";

import { Input } from "@/components/ui/input";

export function InputPreview() {
  const [value, setValue] = useState("");

  return (
    <div className="flex w-full items-center justify-center px-4 py-6">
      <div className="flex w-full max-w-sm flex-col gap-2.5">
        <Input
          description="We only use this for account notifications."
          label="Work email"
          onValueChange={setValue}
          placeholder="name@company.com"
          showClear
          value={value}
        />
        <p className="text-pretty text-left text-[13px] text-muted-foreground leading-snug tracking-tight sm:text-sm">
          Type to watch the spring caret follow each keystroke.
        </p>
      </div>
    </div>
  );
}

Props

Props
Description

Input

value

Controlled input value. Pair with `onValueChange` or `onChange` when the parent owns the text.

Type string

defaultValue

Initial value for uncontrolled usage.

Type string

onValueChange

Base UI change handler with the next string value and event metadata. Preferred for controlled forms.

Type (value: string, eventDetails: InputChangeEventDetails) => void

onChange

Native change handler fired after typing, paste, cut, or autofill.

Type React.ChangeEventHandler<HTMLInputElement>

type

Native input type. Smooth caret is enabled for text-like types only (`text`, `search`, `url`, `email`, `password`, `tel`).

Type React.HTMLInputTypeAttribute·Default text

label

Optional field label rendered above the control with an associated `htmlFor` id.

Type React.ReactNode

labelClassName

Classes merged onto the optional label element.

Type string

description

Optional helper text rendered below the input shell and linked with `aria-describedby`.

Type React.ReactNode

descriptionClassName

Classes merged onto the description element.

Type string

errorMessage

Validation message rendered below the field. Also sets `aria-invalid` and links through `aria-describedby`.

Type React.ReactNode

errorMessageClassName

Classes merged onto the error message element.

Type string

invalid

Applies destructive shell styling and forwards `aria-invalid` to the native input.

Type boolean·Default false

required

Forwards native required validation and appends a visual asterisk to the label.

Type boolean·Default false

size

Controls the input shell height.

Type "sm" | "default"·Default default

shellClassName

Classes merged onto the bordered input shell.

Type string

wrapperClassName

Classes merged onto the outer field wrapper when `label`, `description`, or `errorMessage` is set. Otherwise merged onto the shell.

Type string

startAdornment

Optional leading slot rendered inside the input shell.

Type React.ReactNode

endAdornment

Optional trailing slot rendered inside the input shell after built-in actions.

Type React.ReactNode

children

Additional trailing content rendered inside the input shell after adornments and actions.

Type React.ReactNode

showClear

When true, renders a clear button while the field has a value and is not disabled or read-only.

Type boolean·Default false

showPasswordToggle

When `type="password"`, shows a visibility toggle by default. Pass `false` to hide it.

Type boolean

placeholder

Placeholder shown when the field is empty.

Type string

fontSize

Optional pixel font size override for the inner field. Defaults to the standard `text-sm` input sizing.

Type number

spring

Spring config for caret movement. Defaults to stiffness 500, damping 30, mass 0.5.

Type { stiffness?: number; damping?: number; mass?: number }

id

Optional id forwarded to the input. A generated id is used when omitted so labels stay associated.

Type string

className

Classes merged onto the native input element. Base UI also supports a state callback.

Type string | ((state: InputState) => string)

style

Inline styles merged onto the native input element. Base UI also supports a state callback.

Type React.CSSProperties | ((state: InputState) => React.CSSProperties)

render

Base UI render override for the native input element. Custom renders disable the smooth caret.

Type React.ReactElement | ((props: React.ComponentProps<'input'>) => React.ReactElement)

disabled

Disables interaction on the native input.

Type boolean·Default false

readOnly

Keeps the field focusable while applying muted shell styling and blocking edits.

Type boolean·Default false

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @base-ui/react/input, motion.

This page documents the Base UI install only. Input uses the Base UI Input primitive for value handling and Field integration.

The generated registry file is /r/input.json.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.

We only use this for account notifications.