InputGroup
Add contextual controls and text around an input.
This component is in beta. Its visual styling is still being updated after the move to Whisk/UI. The API and behavior documented here are stable.
Overview
InputGroup gives one TextInput a shared frame with fixed context or a nearby action. The control remains native, and your application still owns its value and behavior.
Use when
An input needs a fixed prefix, suffix, or adjacent contextual action.
Use instead
Use Field for the label, description, and error. Use TextareaGroup for a textarea with a shared frame, especially when it needs a bottom-row action or its outer frame must own the resize grip. An adornment never replaces the label.
Usage
import { Field, InputGroup, TextInput } from "@smoothie-framework/whisk-react";
<Field
label="Project URL"
description="Enter the domain without https://."
>
<InputGroup startElement={<span aria-hidden="true">https://</span>}>
<TextInput name="projectUrl" placeholder="smoothie.dev" />
</InputGroup>
</Field>Examples
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>Unit
Put a fixed, visual-only unit in an end adornment. If people choose the unit, use a labelled Select or another explicit control instead.
import { Field, InputGroup, TextInput } from "@smoothie-framework/whisk-react";
<Field label="Seats per workspace">
<InputGroup endElement={<span aria-hidden="true">seats</span>}>
<TextInput
name="seatCount"
type="number"
min={1}
inputMode="numeric"
placeholder="25"
/>
</InputGroup>
</Field>Character count
Place InputCharacterCount below the group. It reads the Field-owned native control but does not impose the limit, so pair it with maxLength when the limit is enforced.
import {
Field,
InputCharacterCount,
InputGroup,
Stack,
TextInput,
} from "@smoothie-framework/whisk-react";
<Field label="Workspace handle">
<Stack gap={1}>
<InputGroup startElement={<span aria-hidden="true">@</span>}>
<TextInput maxLength={20} defaultValue="atlas" />
</InputGroup>
<InputCharacterCount aria-label="Workspace handle characters" />
</Stack>
</Field>Action
Use InputGroupAction for a secondary action such as Paste. It is revealed when the group receives focus, so use an always-visible Button when the action must remain available at a glance.
import {
Field,
InputGroup,
InputGroupAction,
TextInput,
} from "@smoothie-framework/whisk-react";
function pasteFromClipboard() {
// Read and apply the clipboard value in application code.
}
<Field label="Invitee email">
<InputGroup
endElement={
<InputGroupAction onClick={pasteFromClipboard}>
Paste
</InputGroupAction>
}
>
<TextInput name="email" type="email" placeholder="maya@example.com" />
</InputGroup>
</Field>Search
Use an always-visible Button for a primary action such as Search. Use InputGroupAction instead for a secondary action that can appear on focus.
import {
Button,
Field,
InputGroup,
TextInput,
} from "@smoothie-framework/whisk-react";
function runSearch() {
// Start the application search.
}
<Field label="Search documentation">
<InputGroup
endElement={
<Button type="button" variant="secondary" onClick={runSearch}>
Search
</Button>
}
>
<TextInput name="query" type="search" placeholder="Search" />
</InputGroup>
</Field>Clearable
Keep the value in application state. InputGroupClear is revealed when the group receives focus, calls onClear, and defaults to the accessible name “Clear input”.
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}
onInput={(event) => setQuery(event.currentTarget.value)}
/>
</InputGroup>
</Field>
);
}Keyboard shortcut
Show a shortcut as a visual hint when the command is available. The Field label names the input; the hint is not part of its accessible description.
import {
Code,
Field,
InputGroup,
TextInput,
} from "@smoothie-framework/whisk-react";
<Field label="Command palette">
<InputGroup
endElement={
<span aria-hidden="true">
<Code as="kbd">⌘K</Code>
</span>
}
>
<TextInput placeholder="Search commands" />
</InputGroup>
</Field>Loading
Use Spinner for a short asynchronous status. Its label is announced as a polite status; it does not become part of the input's accessible description.
import {
Field,
InputGroup,
Spinner,
TextInput,
} from "@smoothie-framework/whisk-react";
<Field label="Search documentation">
<InputGroup endElement={<Spinner size="sm" label="Searching documentation" />}>
<TextInput type="search" defaultValue="deployment" />
</InputGroup>
</Field>Props
Component props
Shared props
Accessibility
InputGroup is a visual container, not a labelled control or a semantic group. Use Field or Label to name the nested TextInput. Text adornments are ordinary sibling text: InputGroup does not connect them with aria-describedby, so they are not announced when the control receives focus, though a reader may encounter them while navigating. Put essential context in the Field label or description and mark visual-only text adornments aria-hidden. Whisk/UI icons are decorative by default; give every interactive adornment its own accessible name and keep its action separate from the control's value and validation behavior.
Content guidance
Use prefixes and suffixes for stable context such as a URL scheme or unit. They do not replace the input label.