Skip to content
Browse documentation
whisk/ui
beta

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

Enter the domain without https://.
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.

0
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.

Searching documentation
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

PropTypeDefaultDescription
childrenTextInputnoneProvide one direct TextInput. The group supplies its frame while the control keeps native value, form, and event behavior.
startElement | endElementReactNodenonePlace visual context, decorative content, or a separate action before or after the control.
sizesm | md | lgmdSet the shared density. It overrides the nested control's standalone size.
variantfilled | outline | flushedfilledSet the shared frame treatment. It overrides the nested control's standalone variant.
focusRing | focusVisibleRinginside | outside | mixed | nonetheme defaultConfigure focus-ring placement for the group, with focusVisibleRing taking precedence for keyboard-visible focus.
InputGroupAction | InputGroupClear | InputCharacterCountrelated partsnoneUse InputGroupClear for a host-owned clear flow and InputCharacterCount for a live count. InputGroupAction is a focus-revealed auxiliary button; the host owns all action behavior and state changes.

Shared props

PropSupportedNotes
as / asChildNoInputGroup always renders its native div frame.
Style propsNoInputGroup exposes size, variant, and focus-ring props instead. See Style props.
className / styleYesApplied to the group frame.
refYesForwards to the group frame.
Native HTML attributesYesNative div attributes are forwarded to the group frame.

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.