Input
⋯
Input follows Figma Basic Input’s General presentation: a 36px native text control with an 8px
radius. It composes a reusable Base UI Field when given a label, description, or error.
Related components: InputGroup for leading and trailing content,
Text Area, and File Input. The
search example uses InputGroup.
import { Input } from "@nesra/ui/input";
export function EmailField() { return <Input label="Email" name="email" type="email" required />;}Input and Field are also available from @nesra/ui. Field has a granular
@nesra/ui/field entrypoint.
Examples
Section titled “Examples”Label and description
Section titled “Label and description”import { Input } from "@nesra/ui/input";
export function InputBasicExample() { return ( <div className="w-full max-w-sm"> <Input label="Email" name="email" type="email" placeholder="Type your email" description="Use your work address" required /> </div> );}States
Section titled “States”Focus an enabled input to inspect the focus ring. A value creates the Filled presentation.
error displays the Error presentation. readOnly uses a light gray surface and default cursor while keeping the
value focusable and included in form submission. disabled prevents editing and form submission.
import { Input } from "@nesra/ui/input";
export function InputStatesExample() { return ( <div className="grid w-full max-w-sm gap-nesra-spacing-lg"> <Input label="Default" placeholder="Type your email" description="Use your work address" /> <Input label="Filled" defaultValue="jessietan@mail.com" description="Use your work address" /> <Input label="Kode" defaultValue="BNK-008" readOnly /> <Input label="Error" defaultValue="invalid" error="Enter a valid email address" /> <Input label="Disabled" placeholder="Type your email" description="Unavailable" disabled /> </div> );}State colors
Section titled “State colors”Input, Text Area, InputGroup, Select, Combobox, Multi Select, Input OTP, and File Input share these roles. Use the theme switch to compare Light and Dark.
| State | Border | Shadow | Content |
|---|---|---|---|
| Default | stroke-border |
— | Value text-body, placeholder text-support, icons icon-muted |
| Focused | stroke-brand-primary |
shadow-nesra-focus-ring |
Same as Default |
| Error | stroke-destructive |
shadow-nesra-destructive |
Message text-destructive |
| Disabled | stroke-border |
— | Label, value, and help text text-disabled, icons icon-disabled |
- The field surface is
surface-card-bg-neutralin every state, including Disabled. Only areadOnlyInput usessurface-card-bg-brand-primary-50. - The focus ring follows
:focus-visible. Text controls match it on every focus, including a click. - The Error ring stays while the field has focus, so it replaces the focus ring.
erroron the component or a Base UI Field sets it. A bareInputorTextareaalso shows it when you setaria-invalid="true". shadow-nesra-focus-ringis a 3px ring ofeffects-focus-ring, gray-600 in Light and gray-400 in Dark.shadow-nesra-destructiveis a 3px ring ofeffects-focus-ring-destructive, red-600 at 20% in Light and red-400 at 20% in Dark.- In Dark, under
.darkor[data-theme="dark"], the surface is gray-900,stroke-borderis gray-700,text-supportis gray-400, andtext-disabledis gray-500. Value, placeholder, help, and error text meet 4.5:1 contrast in both modes. Disabled text is exempt from that minimum.
Controlled value
Section titled “Controlled value”onValueChange receives the current string value. Use value and onValueChange together when the
consuming page owns the input state.
import { useState } from "react";import { Input } from "@nesra/ui/input";
export function InputControlledExample() { const [value, setValue] = useState("");
return ( <div className="w-full max-w-sm"> <Input label="Search" name="search" placeholder="Search projects" value={value} onValueChange={setValue} description={`${value.length} characters entered`} /> </div> );}Bare Input
Section titled “Bare Input”A bare Input needs an accessible name even when it has a placeholder.
import { Input } from "@nesra/ui/input";
export function InputBareExample() { return <Input aria-label="Search projects" name="search" placeholder="Search projects" />;}Reusable Field
Section titled “Reusable Field”Input already creates a Field when given label, description, or error. Most pages do not
need to import Field directly. Use Field to compose a bare control with Field-level options such
as validationMode. Set required on both: Field shows the marker, while the control enables
native required validation.
import { Field } from "@nesra/ui/field";import { Input } from "@nesra/ui/input";
export function InputFieldExample() { return ( <div className="w-full max-w-sm"> <Field label="Project code" description="Use six letters or numbers" validationMode="onBlur" required > <Input name="projectCode" pattern="[A-Za-z0-9]{6}" maxLength={6} required /> </Field> </div> );}Accessibility
Section titled “Accessibility”labelassociates a visible label with the input. For a bareInput, provide an accessible name witharia-label,aria-labelledby, or an external native label. Placeholder text is not a label.descriptionbecomes the input’s accessible description.errorreplaces it with an associated alert. The consuming form owns validation timing and message content.required,disabled,name,id,value,defaultValue, and other native input attributes reachInput. Its forwarded ref points to the native input element.readOnlyprevents editing while preserving keyboard focus and form submission.
API reference
Section titled “API reference”| Prop | Type | Default | Effect |
|---|---|---|---|
label |
ReactNode |
— | Adds a visible Base UI Field label. |
description |
ReactNode |
— | Adds help text below the input. |
error |
FieldError |
— | Displays an associated validation message. |
readOnly |
boolean |
false |
Prevents edits and uses a light gray surface and default cursor. |
Input inherits Base UI Input and native input props. onChange receives a React event.
onValueChange receives the string value. Use value for a controlled input or defaultValue for
an uncontrolled input. The ref points to the native input element.
| Prop | Type | Default | Effect |
|---|---|---|---|
children |
ReactNode |
— | Control to label and describe. |
label |
ReactNode |
— | Visible label for the child control. |
description |
ReactNode |
— | Help text when there is no error. |
error |
FieldError |
— | Error text. match uses Base UI validity. |
required |
boolean |
false |
Shows the required marker only. |
Field forwards Base UI Field Root props such as name, disabled, invalid, and
validationMode. Its ref points to the Field root element.
FieldError
Section titled “FieldError”FieldError is string | { message: ReactNode; match: boolean | keyof ValidityState }. A nonempty
string always displays its message. For an object, true always shows the message, false hides it,
and a ValidityState key shows it when that browser validity condition matches. The type is exported from
@nesra/ui and @nesra/ui/field.
The visual values come from the color roles, typography roles, layout scale, and shape and elevation tokens.