Skip to content
Browse documentation
whisk/ui

Composer

Collect a user message and its related actions.

Overview

Composer is a controlled message-composition surface. It combines a native textarea with send, stop, attachment, and application-defined tool actions while the application owns the draft, work status, files, and message transport.

Use when

Your application owns a controlled message draft and needs a composed send, stop, attachment, or tool surface around it.

Use instead

Use Textarea for an ordinary multiline form field. Use a form and its own submit control when the interaction is not a message or generation workflow.

Usage

import { useState } from "react";
import { Composer } from "@smoothie-framework/whisk-react";

export function WorkspaceComposer() {
  const [value, setValue] = useState("");

  return <Composer
    value={value}
    onValueChange={setValue}
    onSubmit={(message) => {
      sendMessage(message);
      setValue("");
    }}
    inputProps={{ placeholder: "Ask about this workspace" }}
  />;
}

Examples

Reflect application-owned sending state

Composer does not start, await, cancel, or announce generation. Set status to running when your request begins, return it to idle when the request settles, and expose a meaningful application-owned status when people need one.

Ready to send.

import { useState } from "react";
import { Composer, Text } from "@smoothie-framework/whisk-react";

export function AssistantComposer() {
  const [value, setValue] = useState("Summarize the project brief");
  const [status, setStatus] = useState<"idle" | "running">("idle");

  return <>
    <Composer
      value={value}
      onValueChange={setValue}
      status={status}
      onSubmit={() => setStatus("running")}
      onCancel={() => setStatus("idle")}
      inputProps={{ aria-label: "Message" }}
    />
    <Text role="status">
      {status === "running" ? "Generating a response." : "Ready to send."}
    </Text>
  </>;
}

Choose the message shortcut

The default enter mode sends on Enter and retains Shift+Enter for a new line. Use modEnter when the message is usually multi-line, or none when another application interaction owns submission.

tsx
import {
  ComposerActionGroup,
  ComposerFooter,
  ComposerInput,
  ComposerRoot,
  ComposerSubmit,
} from "@smoothie-framework/whisk-react";

<ComposerRoot
  value={value}
  onValueChange={setValue}
  onSubmit={sendMessage}
  submitMode="modEnter"
>
  <ComposerInput aria-label="Message" />
  <ComposerFooter>
    <ComposerActionGroup><ComposerSubmit>Send</ComposerSubmit></ComposerActionGroup>
  </ComposerFooter>
</ComposerRoot>

Compose application-owned actions

The attachment trigger is a button, not a file input: connect it to your picker, validate selected files, and render any file state yourself. The same applies to tools such as a model or context selector.

import {
  Button,
  ComposerActionGroup,
  ComposerAttachmentTrigger,
  ComposerFooter,
  ComposerInput,
  ComposerRoot,
  ComposerSubmit,
} from "@smoothie-framework/whisk-react";

<ComposerRoot value={value} onValueChange={setValue} onSubmit={sendMessage}>
  <ComposerInput placeholder="Ask about a document" aria-label="Message" />
  <ComposerFooter>
    <ComposerActionGroup align="start">
      <ComposerAttachmentTrigger onClick={openFilePicker}>Add reference</ComposerAttachmentTrigger>
    </ComposerActionGroup>
    <ComposerActionGroup align="end">
      <Button variant="ghost">Use context</Button>
      <ComposerSubmit>Send</ComposerSubmit>
    </ComposerActionGroup>
  </ComposerFooter>
</ComposerRoot>

Use textarea constraints

ComposerInput accepts the native textarea constraints. Composer calls reportValidity before onSubmit, but your application decides how to persist or display validation results.

tsx
<Composer
  value={value}
  onValueChange={setValue}
  onSubmit={sendMessage}
  inputProps={{
    aria-label: "Message",
    required: true,
    maxLength: 2_000,
    placeholder: "Describe the change you need",
  }}
/>

Props

Component props

PropTypeDefaultDescription
value | onValueChangestring | (value: string) => voidrequired | noneControl the draft. Without onValueChange, the input is read-only.
onSubmit(value: string, event) => voidnoneReceive a valid, available draft. The application sends and clears it when appropriate.
statusidle | runningidlerunning replaces Submit with Cancel. The application moves between states around its own work.
onCancel(event) => voidnoneStop application-owned work. Cancel is disabled when this callback is absent.
submitModeenter | modEnter | noneenterChoose the textarea shortcut: Enter, Ctrl/Cmd+Enter, or no shortcut. Shift+Enter always adds a line break.
canSubmitbooleanvalue.trim().length > 0Override the blank-draft rule. It never bypasses disabled, read-only, running, or native textarea validation.
disabled | readOnly | sizeboolean | boolean | sm | md | lgfalse | false | mdControl availability, editing, and density. Field state also applies to the Composer parts.
inputPropsComposerInputPropsnonePass native textarea attributes such as placeholder, required, maxLength, and aria-label to the one ComposerInput.
attachment | toolsComposerAttachmentTriggerProps | ReactNodenone | noneAdd an application-owned attachment action or additional actions. Composer does not select, upload, or retain files.
sendLabel | stopLabelstring | stringSend message | Stop generatingName the compact Send and Cancel buttons when the default labels do not describe the action.
sendIcon | stopIconReactNodearrow | stopReplace the default icons while retaining the built-in icon-only actions and their labels.

Accessibility

ComposerInput is a native textarea. Give it a Field label or an aria-label; it uses Message composer only when neither is present. Native Tab order applies because Footer and ActionGroup are not ARIA toolbars. In enter mode, Enter submits and Shift+Enter adds a line break; modEnter requires Ctrl/Cmd+Enter. Submit validates the textarea before calling onSubmit. The running state changes the visible action but does not announce work, so expose meaningful progress or errors in application-owned persistent content or a status region.

Content guidance

Use a Field label or aria-label that says what the person can send. A placeholder can give one brief, realistic example, but it must not carry instructions that are needed to use the composer.