Skip to content
Browse documentation
whisk/ui

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.

We'll only use this for account recovery.
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.

Enter a complete email address.
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.

https://
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.

$USD
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.

0
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

PropTypeDefaultDescription
typetext | email | password | number | tel | url | searchtextChoose the native single-line input type and its browser keyboard or validation behavior.
value | defaultValuestringnoneControl the current native value or seed an uncontrolled editing session. Neither submits or persists the value on its own.
placeholderstringnoneShow an example when the field is empty.
sizesm | md | lgmdChoose the input density.
variantfilled | outline | flushedfilledChoose the visual frame treatment.
name | form | autoComplete | inputModenative input attributesnoneParticipate in forms and give the browser an appropriate autofill or keyboard hint.
required | disabled | readOnlybooleanfalseUse native constraint, availability, and read-only behavior. Field can share these states with its one control.
invalidbooleanfalseApply invalid semantics and styling. Pair it with visible error feedback from Field.
min | max | step | pattern | maxLengthnative input attributesnoneSet browser constraints appropriate to the selected type; application validation still owns the final decision.
focusRing | focusVisibleRinginside | outside | mixed | nonetheme defaultConfigure focus-ring placement, with focusVisibleRing taking precedence for keyboard-visible focus.

Shared props

PropSupportedNotes
as / asChildNoTextInput always renders its native input host.
Style propsNoTextInput exposes semantic input props instead of the shared style-prop surface. See Style props.
className / styleYesApplied to the native input.
refYesForwards to the native input.
Native HTML attributesYesNative input attributes are forwarded.

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.