Input
A text input field with optional start/end icon decoration and an interactive in-field action slot.
Installation
npx shadcn@latest add https://ui.mattdowney.com/r/input.jsonUsage
import { Input } from "@/components/ui/input"Examples
Default
The plain field. It is full-width, so give it a width or a cap (max-w-xs here) or it takes whatever its container happens to be.
Sizes
Heights are 24/28/32/40, the same ramp and the same names as Button, so the same size on a field and the button beside it gives one height and one corner radius. The pair at the bottom is the case this exists for: a field and its submit, stacked at the same width.
With Icons
iconStart and iconEnd render decorative, non-interactive icons inside the field. Same two forms as Button: an element (<Search />) or a bare component (Search).
With Action
actionEnd renders an interactive control inside the field: a copy, clear, or reveal-password button. Pass an icon-sm Button.
States
Default, read-only and disabled side by side. Read-only sits flat on the muted fill at full opacity and still takes focus, so its value can be selected and copied; disabled dims to 70% and does not.
Clear button
Press the X: the old text sinks and fades as the field empties. The value clears at once; the fade is a picture only, and typing never plays it. Needs a controlled value. Show the clear button only while there is text.
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "default" | "ghost" | "default" | default is the bordered form field. ghost is borderless and transparent with no forced height or font-size and minimal focus, for title composers and inline-edit fields; size it via className. |
| size | "xs" | "sm" | "default" | "lg" | "default" | Control height (24/28/32/40), using Button's size names so the same size on a field and the button beside it gives the same height and the same corner radius. Height, side padding, radius, and adornment icon size (12/14/14/16px, Button's ramp) move together. Ignored by ghost, which has no chrome. Note that this replaces the native HTML size attribute, which sets character width and is superseded by className="w-*". |
| iconStart | TablerIcon | ReactNode | None | Decorative, non-interactive icon rendered at the leading edge of the field. Prefer an element (<Search />); a bare component (Search) still works but cannot be passed from a Server Component. |
| iconEnd | TablerIcon | ReactNode | None | Decorative, non-interactive icon rendered at the trailing edge of the field. Prefer an element (<Mail />); a bare component still works but cannot be passed from a Server Component. |
| actionEnd | React.ReactNode | None | Interactive element rendered inside the field at the trailing edge: a copy, clear, or reveal-password button. Pass an icon-sm Button. Its glyph is resized to the field's icon size, the same as iconStart. |
| clearEcho | boolean | false | When the value goes from text to empty without a keystroke (a clear button, a reset), the old text sinks 8px and fades out over 200ms, then the placeholder fades in. The real value is empty at once. Needs a controlled value; off under reduced motion. |
| className | string | None | Applied to the input itself, or to the wrapper div when any icon/action adornment or clearEcho is present. |
variant"default" | "ghost" = "default"default is the bordered form field. ghost is borderless and transparent with no forced height or font-size and minimal focus, for title composers and inline-edit fields; size it via className. |
size"xs" | "sm" | "default" | "lg" = "default"Control height (24/28/32/40), using Button's size names so the same size on a field and the button beside it gives the same height and the same corner radius. Height, side padding, radius, and adornment icon size (12/14/14/16px, Button's ramp) move together. Ignored by ghost, which has no chrome. Note that this replaces the native HTML size attribute, which sets character width and is superseded by className="w-*". |
iconStartTablerIcon | ReactNodeDecorative, non-interactive icon rendered at the leading edge of the field. Prefer an element (<Search />); a bare component (Search) still works but cannot be passed from a Server Component. |
iconEndTablerIcon | ReactNodeDecorative, non-interactive icon rendered at the trailing edge of the field. Prefer an element (<Mail />); a bare component still works but cannot be passed from a Server Component. |
actionEndReact.ReactNodeInteractive element rendered inside the field at the trailing edge: a copy, clear, or reveal-password button. Pass an icon-sm Button. Its glyph is resized to the field's icon size, the same as iconStart. |
clearEchoboolean = falseWhen the value goes from text to empty without a keystroke (a clear button, a reset), the old text sinks 8px and fades out over 200ms, then the placeholder fades in. The real value is empty at once. Needs a controlled value; off under reduced motion. |
classNamestringApplied to the input itself, or to the wrapper div when any icon/action adornment or clearEcho is present. |
"use client"
import * as React from "react"
import { Input as InputPrimitive } from "@base-ui/react/input"
import { cn } from "@/registry/lib/utils"
import { renderIconProp, type IconProp } from "@/registry/lib/icon-prop"
// `size` is omitted from the native props on purpose: HTML's own `size` is a
// NUMBER (visible character width) and would collide with the control-height
// prop below. The native one is near-useless next to `className="w-*"`, so the
// design-system meaning wins the name.
type InputProps = Omit<React.ComponentProps<"input">, "size"> & {
/**
* Visual treatment:
* - "default" → the standard bordered form field (h-8, bg, shadow-xs).
* - "ghost" → borderless/transparent, no forced height or font-size, minimal
* focus (no ring/border swap). Size it via `className`
* (e.g. `text-2xl h-auto`). For title composers and inline-edit fields.
*/
variant?: "default" | "ghost"
/**
* Control height, matching Button's ramp name for name, so an Input and a
* Button given the same `size` are the same height and can sit in one row or
* one stacked form without a hand-tuned `className`. Ignored by `ghost`,
* which has no chrome and is sized by the caller.
*/
size?: "xs" | "sm" | "default" | "lg"
/** Decorative, non-interactive icon at the leading edge. Takes an ELEMENT
* (`<Search />`) or a bare component (`Search`), same as Button. Prefer the
* element: it is the only form that can be passed from a Server Component. */
iconStart?: IconProp
/** Decorative, non-interactive icon at the trailing edge. Same two forms as
* `iconStart`. */
iconEnd?: IconProp
/** Interactive element rendered inside the field at the trailing edge - e.g.
* a copy, clear, or reveal-password button. Unlike `iconEnd` (decorative,
* non-interactive), this receives pointer events. Pass a Button/icon-button. */
actionEnd?: React.ReactNode
/** When something other than typing empties the field (a clear button in
* `actionEnd`, a form reset), the old text sinks and fades out instead of
* vanishing. The value is already empty when it starts: the text you see
* leave is a picture only, so forms and screen readers get the empty field
* at once. Needs a controlled `value`. Off under reduced motion. */
clearEcho?: boolean
}
// Height + side padding + radius move together, exactly as they do on Button:
// radius reads the action ramp (3/8 of the height) so a field and the button
// under it are the same shape, and padding steps a constant 4px. A form
// control is not a squarer tier than an action any more; one control language.
// Type holds at the `default` step from `sm` up, because a text field you type
// into should not shrink its content below 13px just to fit a shorter box.
// The side padding and type are their own table because the clear echo
// (below) sets its text exactly where the field sets its own.
const SIZE_TEXT = {
// `text-field` (16px) on mobile at every size, including this one: iOS zooms
// the viewport on focus for any field under 16px, and no height is worth that.
// Not `text-base`, which is the 15.5px reading size.
// The step-down is desktop-only.
xs: "px-2 text-field md:text-1xs",
sm: "px-3 text-field md:text-sm",
default: "px-3 text-field md:text-sm",
lg: "px-4 text-field md:text-sm",
} as const
const SIZE_CLASSES = {
xs: cn("h-6 rounded-action-xs", SIZE_TEXT.xs),
sm: cn("h-7 rounded-action-sm", SIZE_TEXT.sm),
default: cn("h-8 rounded-action", SIZE_TEXT.default),
lg: cn("h-10 rounded-action-lg", SIZE_TEXT.lg),
} as const
// Positioning, size, and colour are the field's business, not the caller's, so
// they are applied to the icon in either form. `renderIconProp` puts them after
// an element's own className, so these win the merge.
const ICON_CLASSES =
"absolute top-1/2 -translate-y-1/2 text-muted-foreground pointer-events-none z-10"
// The icon box follows Button's ramp for the same size name (12 / 14 / 14 / 16
// across xs / sm / default / lg), so a field and the button under it carry the
// same glyph. It was a flat 12px at every size, which read tiny next to 14px
// type in a 32px field. `xs` holds at 12 for the reason Button's does: its box
// is 24px and the size exists for dense rows.
//
// Each entry also carries the text clearance that box implies. Clearance is
// where the adornment ends plus the kit's 8px icon-to-text gap (`gap-2` on
// Select, Combobox, Dropdown items, Nav). An icon sits at `left-3`/`right-3`,
// so text starts at 12 + icon + 8: 32 / 34 / 34 / 36px. Derived, not
// eyeballed: an older 28/28/40 read as 4px, 4px, and 12px gaps.
const ICON_SIZE = {
xs: { icon: "size-3", action: "[&_svg]:size-3!", start: "ps-8", end: "pe-8" },
sm: { icon: "size-3.5", action: "[&_svg]:size-3.5!", start: "ps-8.5", end: "pe-8.5" },
default: { icon: "size-3.5", action: "[&_svg]:size-3.5!", start: "ps-8.5", end: "pe-8.5" },
lg: { icon: "size-4", action: "[&_svg]:size-4!", start: "ps-9", end: "pe-9" },
} as const
// The clear echo: a copy of the old text laid over the field, in the field's
// own padding, type and border, that sinks 8px, blurs 2px and fades out on the
// large role (200ms): at 150ms the text was gone before the sink could be seen. It plays only when the
// value goes from text to empty without a keystroke, so selecting all and
// deleting stays instant: typing never animates. The real value is already
// empty underneath, so the placeholder shows through as the echo leaves and
// there is no blank beat. `fill-mode-forwards` holds the last frame until the
// echo unmounts, so it cannot flash back for a frame first.
const ECHO_CLASSES =
"pointer-events-none absolute inset-0 flex items-center overflow-hidden whitespace-pre text-foreground animate-out fade-out slide-out-to-bottom-2 blur-out-2xs fill-mode-forwards duration-large ease-large motion-reduce:animate-none motion-reduce:hidden"
// While the echo leaves, the placeholder waits out of sight, then fades in on
// the small role once the echo is gone. Shown at once, the two lines of text
// sat on top of each other for the length of the fade and read as a smudge.
// The transition is only on the way in: hiding it has to be instant.
const PLACEHOLDER_WAITING = "placeholder:opacity-0"
const PLACEHOLDER_ARRIVING = "placeholder:transition-opacity placeholder:duration-small placeholder:ease-small motion-reduce:placeholder:transition-none"
// @use-when a single-line text field.
function Input({ className, type, variant = "default", size = "default", iconStart, iconEnd, actionEnd, clearEcho = false, onChange, ...props }: InputProps) {
const hasIconStart = !!iconStart
const hasIconEnd = !!iconEnd
const hasActionEnd = !!actionEnd
const iconSize = ICON_SIZE[size]
// Watch the controlled value. A keystroke marks the next change as typed;
// any other change to empty plays the echo of what was there.
const [echo, setEcho] = React.useState<{ text: string; id: number } | null>(null)
const typedRef = React.useRef(false)
const prevValueRef = React.useRef(props.value)
React.useLayoutEffect(() => {
const prev = prevValueRef.current
prevValueRef.current = props.value
const typed = typedRef.current
typedRef.current = false
if (!clearEcho || typed) return
if (typeof prev !== "string" || prev === "" || props.value !== "") return
if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return
setEcho({ text: prev, id: Date.now() })
}, [props.value, clearEcho])
const handleChange: React.ChangeEventHandler<HTMLInputElement> = (event) => {
typedRef.current = true
onChange?.(event)
}
// Shared by both variants: color/placeholder/selection, full-width sizing,
// native outline reset, file-input reset, and disabled state.
const commonClasses = "file:text-foreground placeholder:text-subtle-foreground selection:bg-accent selection:text-accent-foreground w-full min-w-0 outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-70"
// default: the bordered form-control chrome (fixed height, fill, shadow,
// neutral focus border, destructive invalid state). Hover darkens the border one
// step (`border-strong`, pointer devices only, and only while it can be
// edited); focus and invalid sort after hover in the stylesheet, so they win.
// Read-only sits flat on the
// muted fill at full opacity: it can still be focused, selected and copied,
// so it must not look disabled, but it must not look typeable either.
const defaultClasses = cn(
"border-border border bg-input-bg bg-clip-padding backdrop-blur-sm shadow-xs transition-[color,box-shadow,border-color] duration-small ease-small hover:border-border-strong read-only:hover:border-border focus-visible:border-border-focus aria-invalid:border-destructive [&[readonly]]:bg-muted [&[readonly]]:shadow-none disabled:bg-muted disabled:shadow-none",
SIZE_CLASSES[size]
)
// ghost: no chrome. No forced height or font-size (caller sizes via className),
// no ring/border on focus. Flush left (px-0); adornment clearance still applies.
const ghostClasses = "border-0 bg-transparent px-0 shadow-none focus-visible:ring-0"
const inputClasses = cn(commonClasses, variant === "ghost" ? ghostClasses : defaultClasses)
// Without any adornment or echo, apply className directly to input
if (!hasIconStart && !hasIconEnd && !hasActionEnd && !clearEcho) {
return (
<InputPrimitive
type={type}
data-slot="input"
className={cn(inputClasses, className)}
onChange={onChange}
{...props}
/>
)
}
const clearance = cn(hasIconStart && iconSize.start, hasIconEnd && iconSize.end, hasActionEnd && "pe-9")
// With an adornment, className goes on the wrapper; input gets clearance padding
return (
<div className={cn("relative", className)}>
{renderIconProp(iconStart, {
"aria-hidden": "true",
className: cn(ICON_CLASSES, iconSize.icon, "start-3"),
})}
<InputPrimitive
type={type}
data-slot="input"
// Icon clearance comes from ICON_SIZE above. An action's clearance
// does not move with the ramp: an `icon-sm` button is a 24px box at
// every field size, so at `right-1` it ends at 28 and text stops at
// 36 whatever glyph it holds.
className={cn(inputClasses, clearance, clearEcho && (echo ? PLACEHOLDER_WAITING : PLACEHOLDER_ARRIVING))}
onChange={handleChange}
{...props}
/>
{echo && (
<span
key={echo.id}
aria-hidden
data-slot="input-clear-echo"
className={cn(
ECHO_CLASSES,
variant === "ghost" ? "px-0" : cn("border border-transparent", SIZE_TEXT[size]),
clearance
)}
onAnimationEnd={() => setEcho(null)}
>
{echo.text}
</span>
)}
{renderIconProp(iconEnd, {
"aria-hidden": "true",
className: cn(ICON_CLASSES, iconSize.icon, "end-3"),
})}
{actionEnd && (
// The glyph inside the action takes the field's icon size, so a
// reveal-password eye matches a leading search icon in the same field.
// `!` because the Button inside sets its own `[&_svg]:size-*` at the
// same specificity, and which of two equal rules wins is compile order.
<div className={cn("absolute end-1 top-1/2 z-10 flex -translate-y-1/2 items-center", iconSize.action)}>
{actionEnd}
</div>
)}
</div>
)
}
export { Input }
export type { InputProps }