Hint

Software update

Check for updates

Track

import {
  SegmentedControl, SettingsGroup, SettingsRow, Switch,
} from "@arcadia/ui";

<SettingsGroup label="Software update">
  <SettingsRow label="Check for updates" control={<Switch hideLabel label="Check for updates" defaultChecked />} />
  <SettingsRow label="Track" hint="Staging gets test builds before they are released."
    control={<SegmentedControl size="md" aria-label="Track" defaultValue="stable"
      items={[{ value: "stable", label: "Stable" }, { value: "staging", label: "Staging" }]} />} />
</SettingsGroup>

TSX

import { Hint } from "@arcadia/ui";

<span>
  Keep the cache warm
  <Hint label="Keep the cache warm" text="Sends a short request before a chat's cache expires, so the next message costs less." />
</span>

A question mark after a label, for the setting its name cannot explain. A page at rest shows names and controls; the sentence waits in a tooltip until someone asks for it. A setting whose name says what it does takes no hint at all, and most do.

The text is one or two sentences, at most 160 characters, and plain: no links, no controls. SettingsRow, SettingsGroup, Field and Switch take it as hint, and a SegmentedControl item takes one per choice, so the hint is rarely placed by hand. Something a person must read to act safely is not a hint: it is a SettingsNotice, shown on the page.

Examples

Open

Rendered pinned in place. Beside a label the glyph takes the label's letter height and its stem; the button around it is 24px and does not change the line's height.

Pinned by a click, Enter or Space

Beside any label

The glyph sits on its label's line as a letter would: its middle is the middle of the label's capitals, at the label's size and stem.

Keep the cache warmKeep the cache warmKeep the cache warm

import { Hint } from "@arcadia/ui";

function Sizes() {
  const text = "Sends a short request before a chat's cache expires.";
  return (
    <div {...sx("hint-sizes", styles.sizes)}>
      <span {...sx("hint-small", styles.small)}>Keep the cache warm<Hint label="Keep the cache warm" text={text} /></span>
      <span>Keep the cache warm<Hint label="Keep the cache warm" text={text} /></span>
      <span {...sx("hint-large", styles.large)}>Keep the cache warm<Hint label="Keep the cache warm" text={text} /></span>
    </div>
  );
}

On a field

Field puts the hint after its label and gives the text to the control as its description.

Command

import { Field, Input } from "@arcadia/ui";

<Field label="Command" hint="Runs with your environment, without the app's own variables.">
  <Input placeholder="npx -y @acme/server" />
</Field>

In a form the hint stays out of the Tab order, so Tab goes field to field; the control already carries the sentence.

On a group

A group's hint explains what its rows share.

Environment

API_TOKENAdded Oct 3

import { SettingsGroup, SettingsRow } from "@arcadia/ui";

<SettingsGroup label="Environment" hint="Stored on this device only. A saved value is never shown again.">
  <SettingsRow label="API_TOKEN" meta="Added Oct 3" />
</SettingsGroup>

On each choice

When the choices need the explaining, each segment carries its own: the tooltip opens on that segment.

import { SegmentedControl } from "@arcadia/ui";

<SegmentedControl size="md" aria-label="When you send" defaultValue="queue"
  items={[
    { value: "queue", label: "Queue", hint: "Sent when the agent finishes." },
    { value: "steer", label: "Steer", hint: "Read at the agent's next step, without stopping it." },
  ]} />

The hint is a button named About and its label, described by its text, so a screen reader hears the sentence on the button without opening anything. In the tab order it follows its label and comes before the row's control. Field and Switch also give the text to their control as its description. It opens when the pointer rests on it and at once on keyboard focus; a press pins it, so touch and keyboard users can read it without holding anything.

Enter or Space: Pins the hint open, or closes it
Esc: Closes the hint and nothing under it
Tab: Moves on to the control; the hint closes

labelrequired: string; What it explains: the button's accessible name is About ${label}.
textrequired: string; One or two sentences, at most 160 characters. Plain text: no links, no controls, no markup.
side: "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end"Default "top"
defaultOpen: booleanDefault false; Starts pinned open (a specimen, a first-run pointer).
tabbable: booleanDefault true; false keeps it out of the Tab order where its text already describes the control (a form field), so Tab goes field to field; the pointer still opens it.
container: PortalContainerDefault document.body; Portal container for the tooltip.
rootStyle: RootStyle; Typed StyleX override: where the hint sits.