TextInput
Collect a single-line value.
Overview
TextInput is a native, single-line input with Whisk/UI sizing, appearance, focus, and Field integration. Your application owns its value, validation timing, and submission.
Use when
The user enters one line of plain text.
Use instead
Use Textarea for longer content, Select for a fixed choice, or Combobox for searchable choices.
Usage
import { Field, TextInput } from "@smoothie-framework/whisk-react";
<Field label="Workspace name" required>
<TextInput
name="workspaceName"
autoComplete="organization"
placeholder="Atlas"
/>
</Field>Examples
Variants
Choose the frame treatment that fits the surrounding layout.
import { Field, FieldGroup, TextInput } from "@smoothie-framework/whisk-react";
<FieldGroup>
<Field label="Filled">
<TextInput variant="filled" placeholder="Atlas" />
</Field>
<Field label="Outline">
<TextInput variant="outline" placeholder="Atlas" />
</Field>
<Field label="Flushed">
<TextInput variant="flushed" placeholder="Atlas" />
</Field>
</FieldGroup>Sizes
Choose the input size that matches the surrounding form density.
import { Field, FieldGroup, TextInput } from "@smoothie-framework/whisk-react";
<FieldGroup>
<Field label="Small">
<TextInput size="sm" placeholder="Atlas" />
</Field>
<Field label="Medium">
<TextInput size="md" placeholder="Atlas" />
</Field>
<Field label="Large">
<TextInput size="lg" placeholder="Atlas" />
</Field>
</FieldGroup>Helper text
Use Field description for concise guidance that helps someone complete the input.
import { Field, TextInput } from "@smoothie-framework/whisk-react";
<Field label="Email address" description="We'll only use this for account recovery." required>
<TextInput
type="email"
autoComplete="email"
placeholder="name@example.com"
/>
</Field>Error text
Pass a clear validation message to Field after application validation finds a problem.
import { Field, TextInput } from "@smoothie-framework/whisk-react";
<Field label="Email address" error="Enter a complete email address.">
<TextInput type="email" defaultValue="team@" />
</Field>Forms
Use react-hook-form for registration and validation. register works because TextInput forwards its ref and native input props.
import { useForm } from "react-hook-form";
import { Box, Button, Field, Stack, TextInput } from "@smoothie-framework/whisk-react";
type ProfileValues = { firstName: string };
function onSubmit(values: ProfileValues) {
// Send values to your application.
}
export function ProfileForm() {
const { register, handleSubmit, formState: { errors } } = useForm<ProfileValues>();
return (
<Box as="form" noValidate onSubmit={handleSubmit(onSubmit)}>
<Stack gap={3}>
<Field label="First name" required error={errors.firstName?.message}>
<TextInput {...register("firstName", { required: "Enter your first name." })} />
</Field>
<Button type="submit">Save</Button>
</Stack>
</Box>
);
}Start icon
Whisk/UI icons are decorative by default, so the Field label names the input without an extra wrapper.
import { Field, InputGroup, TextInput } from "@smoothie-framework/whisk-react";
import { SearchIcon } from "@smoothie-framework/whisk-react/icons";
<Field label="Search documentation">
<InputGroup startElement={<SearchIcon size="sm" />}>
<TextInput type="search" placeholder="Search" />
</InputGroup>
</Field>Start text
Use start text only when it remains true for every value someone can enter.
import { Field, InputGroup, TextInput } from "@smoothie-framework/whisk-react";
<Field label="Project URL">
<InputGroup startElement="https://">
<TextInput placeholder="smoothie.dev" />
</InputGroup>
</Field>Start and end text
Pair fixed currency context with an amount only when people cannot change the currency here.
import { Field, InputGroup, TextInput } from "@smoothie-framework/whisk-react";
<Field label="Monthly budget">
<InputGroup startElement="$" endElement="USD">
<TextInput inputMode="decimal" placeholder="0.00" />
</InputGroup>
</Field>Disabled
Use disabled when the value is unavailable. Use readOnly instead when people still need to focus or copy it.
import { Field, TextInput } from "@smoothie-framework/whisk-react";
<Field disabled label="Workspace name">
<TextInput defaultValue="Atlas" />
</Field>Read-only
Use readOnly when people need to focus or copy a value but cannot edit it.
import { Field, TextInput } from "@smoothie-framework/whisk-react";
<Field label="Workspace ID">
<TextInput defaultValue="ws_8qVh" readOnly />
</Field>Password visibility
An end Button can change the input type. Use an explicit action name that reflects the next action.
import { useState } from "react";
import { Button, Field, InputGroup, TextInput } from "@smoothie-framework/whisk-react";
export function PasswordInput() {
const [visible, setVisible] = useState(false);
return (
<Field label="Password">
<InputGroup
endElement={
<Button
type="button"
size="sm"
variant="ghost"
aria-label={visible ? "Hide password" : "Show password"}
onClick={() => setVisible(!visible)}
>
{visible ? "Hide" : "Show"}
</Button>
}
>
<TextInput type={visible ? "text" : "password"} autoComplete="current-password" />
</InputGroup>
</Field>
);
}Character counter
InputCharacterCount reads the Field-owned control and is visible below it. It is not announced while typing; pair it with maxLength when the limit is enforced.
import { Field, InputCharacterCount, Stack, TextInput } from "@smoothie-framework/whisk-react";
<Field label="Workspace handle">
<Stack gap={1}>
<TextInput maxLength={20} defaultValue="atlas" />
<InputCharacterCount aria-label="Workspace handle characters" />
</Stack>
</Field>Number constraints
Use native number, minimum, maximum, and step constraints when the input accepts a bounded numeric value.
import { TextInput } from "@smoothie-framework/whisk-react";
<TextInput type="number" min={1} max={10} step={1} defaultValue={2} />Focus rings
Set the ring placement only when the default does not meet the surrounding visual boundary. focusVisibleRing overrides focusRing for keyboard-visible focus.
import { Field, FieldGroup, TextInput } from "@smoothie-framework/whisk-react";
<FieldGroup>
<Field label="Inside"><TextInput focusRing="inside" placeholder="Search projects" /></Field>
<Field label="Outside"><TextInput focusRing="outside" placeholder="Workspace name" /></Field>
<Field label="Keyboard only">
<TextInput focusRing="inside" focusVisibleRing="outside" placeholder="Agent name" />
</Field>
</FieldGroup>Clearable
Keep the value in application state. onInput keeps it synchronized on every keystroke in both adapters. InputGroupClear calls onClear and defaults to the accessible name “Clear input”; it does not change the value or dispatch input events itself.
import { useRef, useState } from "react";
import { Field, InputGroup, InputGroupClear, TextInput } from "@smoothie-framework/whisk-react";
export function SearchInput() {
const inputRef = useRef<HTMLInputElement | null>(null);
const [query, setQuery] = useState("deployment");
return (
<Field label="Search documentation">
<InputGroup endElement={<InputGroupClear controlRef={inputRef} onClear={() => setQuery("")} />}>
<TextInput
ref={inputRef}
type="search"
value={query}
// Keep controlled state in sync on every keystroke in both adapters.
onInput={(event) => setQuery(event.currentTarget.value)}
/>
</InputGroup>
</Field>
);
}Props
Component props
Shared props
Accessibility
Give every TextInput a visible Field label or an accessible name; a placeholder is only an example, never a replacement label. Choose a type that matches the expected value, keep validation feedback visible through Field, and use readOnly rather than disabled when people need to focus or copy the value. Use text with inputMode for numeric-looking identifiers such as account or postal codes, since number creates a spinbutton and changes the input semantics.
Content guidance
Name the value in its label. Use the placeholder for a realistic format or example, not to repeat the label or carry required instructions.