Components

This page catalogs every component that @ada-cx/lovelace exports, grouped by role. Each entry names the component’s purpose and its most important props, and pairs them with a copyable example. Prop types ship with the package as TypeScript declarations, so your editor completes and checks every prop.

Live component gallery

Every component in this catalog renders live below, including each icon glyph. The gallery follows the theme you configure in the theme playground: pick a preset or a scheme on either page, and both pages stay in sync. Overlay components, such as DialogOverlay and SheetOverlay, open from a button inside a contained preview frame in their tile.

The live component gallery could not load in this view. The catalog below describes every component.

Shared conventions

All components follow the same contract:

Every component accepts className and style, and takes ref as a regular prop (React 19).
Interactive components extend the matching React Aria Components props. Use onPress instead of onClick, and isDisabled instead of disabled.
Interactive states render as data-* attributes: data-hovered, data-pressed, data-focus-visible, data-disabled, data-selected. Extend styling by targeting those attributes, not pseudo-classes.
Compound components attach their parts with dot notation, for example Input.Field and Dialog.Title. The parts are not separate exports.
Icon-only controls require a label prop. It becomes the accessible name.

Conversation

Components that render the conversation itself. The chat composer is not a separate export: it is the Input component’s "composer" variant, with a send Input.Button — see Input.

MessageRow

One row of a transcript: an optional avatar gutter, then MessageRow.Content, the column that holds everything belonging to the message. Key props: sender on the row, fill on MessageRow.Content.

sender sets which edge the row aligns to and the typography the column carries. The row imposes no message body. A row that shows prose renders AgentMessage or UserMessage inside the column. A row that shows a card, a widget or media renders neither, and still reads at message size. Set fill when the content supplies no width of its own.

Keep the avatar a sibling of the column rather than a child of it. A reaction bar or a retry control beside the message then aligns with the message text.

import { AgentMessage, Avatar, MessageRow } from "@ada-cx/lovelace";
<MessageRow sender="agent">
  <Avatar aria-hidden size="sm">A</Avatar>
  <MessageRow.Content>
    <AgentMessage>Hi! I can help with orders, billing, and returns.</AgentMessage>
  </MessageRow.Content>
</MessageRow>;

AgentMessage

A single agent message body. The content accepts blocks, such as lists and tables. Key props: children.

Row layout is yours, not the component’s. Place an avatar, a sender name or a retry control beside the body rather than inside it, so they align with the text and stay outside the body’s own text-direction detection. MessageRow supplies that layout. Use <Avatar showAvatar={false}> to hold the gutter on a grouped message that shows no avatar.

import { AgentMessage, Avatar } from "@ada-cx/lovelace";
<div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
  <div style={{ display: "flex", alignItems: "flex-start", gap: 12 }}>
    <Avatar aria-hidden>A</Avatar>
    <AgentMessage>Hi! I can help with orders, billing, and returns.</AgentMessage>
  </div>
  <div style={{ display: "flex", alignItems: "flex-start", gap: 12 }}>
    <Avatar aria-hidden showAvatar={false} />
    <AgentMessage>Which order do you need help with?</AgentMessage>
  </div>
</div>;

UserMessage

The end user’s outbound message bubble, shrink-wrapped to its content. The content accepts blocks, such as lists and tables. Key props: children.

Where the bubble sits is yours: align it to the trailing edge in your own row. Render MessageError beside the bubble when a send fails.

import { UserMessage } from "@ada-cx/lovelace";
<UserMessage>Where is my order?</UserMessage>;

MessageError

The failed-to-send row shown below a message bubble. With onRetry the copy becomes a retry control and names it. Without onRetry the copy renders as static text. Key props: children, onRetry, announce.

The row announces the failure through a visually-hidden role="alert". Set announce to false on a surface that announces message failures through its own live region. Two live regions announce the same text twice.

Without onRetry, the row hides the visible copy from assistive technology while announce stays on. The alert already carries that text. With onRetry, the copy stays exposed, because it names the retry control.

The row also aligns at the leading edge of its container. Put it in an end-aligned column to keep it below the bubble.

import { MessageError, UserMessage } from "@ada-cx/lovelace";
<div style={{ display: "flex", flexDirection: "column", alignItems: "flex-end" }}>
  <UserMessage>This one failed to send.</UserMessage>
  <MessageError onRetry={resend}>Message failed to send. Retry</MessageError>
</div>;

PictureMessage

An image message frame with a built-in “image unavailable” placeholder. Key props: src, alt, aspectRatio ("16:9" | "4:3" | "1:1" | "3:4" | "9:16"), unavailable, onLoadingStatusChange.

import { PictureMessage } from "@ada-cx/lovelace";
<PictureMessage
  src="https://example.com/photo.jpg"
  alt="Order photo"
  aspectRatio="16:9"
/>;

ProactiveMessage

A proactive greeting card shown outside the conversation window. Key props: children.

import { ProactiveMessage } from "@ada-cx/lovelace";
<ProactiveMessage>
  👋 Need a hand picking a plan? I can compare them for you.
</ProactiveMessage>;

Divider

A transcript separator: a plain rule, a labeled marker (for example “1 unread message”), or a centered system message. Key props: variant ("line" | "label" | "message"), heading, children.

import { Divider } from "@ada-cx/lovelace";
<>
  <Divider variant="line" />
  <Divider variant="label">1 unread message</Divider>
  <Divider variant="message" heading="⏳ You are #1 in the queue">
    An agent will be with you shortly.
  </Divider>
</>;

ScrollMarker

A floating jump-to-bottom control; shows an unread pill when messages wait below the fold. Key props: unreadCount, color ("default" | "brand"), onPress, children.

import { ScrollMarker } from "@ada-cx/lovelace";
<ScrollMarker unreadCount={2} onPress={scrollToBottom} />;

The conversation header bar. Compound: Header.Title.

import { Avatar, Header } from "@ada-cx/lovelace";
<Header>
  <Avatar size="md" label="Ada AI Agent">
    A
  </Avatar>
  <Header.Title>Ada</Header.Title>
</Header>;

Actions

Buttons and links that trigger an action.

Button

The standard action button. Key props: variant ("primary" | "secondary" | "tertiary"), size ("md" | "sm"), destructive, onPress, isDisabled.

import { Button } from "@ada-cx/lovelace";
<>
  <Button variant="primary" onPress={submit}>
    Primary
  </Button>
  <Button variant="secondary">Secondary</Button>
  <Button variant="tertiary">Tertiary</Button>
  <Button variant="primary" destructive>
    Delete
  </Button>
</>;

IconButton

An icon-only button. Key props: label (required), variant ("primary" | "secondary" | "tertiary"), size ("md" | "sm" | "xs"), destructive, children (a single icon).

import { IconButton, SendFill } from "@ada-cx/lovelace";
<IconButton label="Send message" onPress={send}>
  <SendFill />
</IconButton>;

PillButton

A pill-shaped secondary action button. Key props: size ("md" | "sm"), onPress, isDisabled.

import { PillButton } from "@ada-cx/lovelace";
<PillButton onPress={endChat}>End chat</PillButton>;

Link

An inline text link, with optional external-link icon and download semantics. Key props: href, underlined, showIcon, download.

import { Link } from "@ada-cx/lovelace";
<Link href="https://docs.ada.cx" underlined showIcon>
  Read the developer docs
</Link>;

Forms and selection

Form and selection controls, including the chat composer.

Input

The text field and chat composer. Compound: Input.Label, Input.Field, Input.Attachments (chip row inside the field, above the control), Input.Control (single line), Input.TextArea (auto-growing multi-line), Input.HelperText, Input.Button. Key props — root: variant ("default" | "composer"), value, onChange, isDisabled, isInvalid; Input.TextArea: minRows, maxRows.

import { Input } from "@ada-cx/lovelace";
<Input aria-label="Email address">
  <Input.Label>Email address</Input.Label>
  <Input.Field>
    <Input.Control placeholder="you@example.com" />
  </Input.Field>
  <Input.HelperText>We reply within a day.</Input.HelperText>
</Input>;

The composer variant adds the send button and an auto-growing text area:

import { Input, SendFill } from "@ada-cx/lovelace";
<Input variant="composer" aria-label="Message">
  <Input.Field>
    <Input.TextArea placeholder="Write a message" minRows={1} maxRows={3} />
    <Input.Button label="Send">
      <SendFill />
    </Input.Button>
  </Input.Field>
</Input>;

Input.Attachments holds attachment chips inside the field, in either variant. Render it as the first child of Input.Field. It takes a full line above the control, and the send button stays on the control’s line:

<Input variant="composer" aria-label="Message">
  <Input.Field>
    <Input.Attachments>
      <span>receipt.png</span>
    </Input.Attachments>
    <Input.TextArea placeholder="Write a message" minRows={1} maxRows={3} />
    <Input.Button label="Send">
      <SendFill />
    </Input.Button>
  </Input.Field>
</Input>;

Input.Field sets flex-wrap: wrap in both variants to allow this. A child that cannot shrink moves to a new line at a narrow width instead of overflowing.

Checkbox

A checkbox with an optional inline label. Key props: isSelected, onChange, children.

import { Checkbox } from "@ada-cx/lovelace";
<Checkbox defaultSelected>Email me a transcript</Checkbox>;

CheckboxGroup

CheckboxGroup groups Checkbox options and owns the selected values. Key props: aria-label, children, onChange, value.

import { Checkbox, CheckboxGroup } from "@ada-cx/lovelace";
<CheckboxGroup aria-label="Topics to follow up on" defaultValue={["billing"]}>
  <Checkbox value="billing">Billing</Checkbox>
  <Checkbox value="delivery">Delivery</Checkbox>
</CheckboxGroup>;

Radio and RadioGroup

RadioGroup groups Radio options with keyboard navigation. Key props — RadioGroup: value, onChange, aria-label, children; Radio: value, children.

import { Radio, RadioGroup } from "@ada-cx/lovelace";
<RadioGroup aria-label="Contact method" defaultValue="chat">
  <Radio value="chat">Continue in chat</Radio>
  <Radio value="email">Switch to email</Radio>
</RadioGroup>;

Toggle

An on/off switch. Track-only: name it with aria-label. Key props: isSelected, onChange, aria-label.

import { Toggle } from "@ada-cx/lovelace";
<Toggle defaultSelected aria-label="Sound on" />;

Chip

A toggle chip for quick replies and filters. Key props: variant ("text" | "icon" | "number"), size ("md" | "lg"), isSelected, onChange, children.

import { Chip } from "@ada-cx/lovelace";
<>
  <Chip defaultSelected>Track my order</Chip>
  <Chip>Talk to an agent</Chip>
</>;

SurveyRating

A numeric or icon rating scale (for example CSAT 1 to 5). Provide aria-label, or use aria-labelledby to reference the visible question label. Key props: aria-label, aria-labelledby, onChange, options, selectedKey, showLabels.

import { SurveyRating } from "@ada-cx/lovelace";
<SurveyRating
  aria-label="How satisfied are you?"
  showLabels
  options={[
    { value: 1, label: "Not satisfied" },
    { value: 2 },
    { value: 3 },
    { value: 4 },
    { value: 5, label: "Very satisfied" },
  ]}
/>;

SurveySelect

A chip group for single or multiple choice survey questions. Provide aria-label, or use aria-labelledby to reference the visible question label. Key props: aria-label, aria-labelledby, disallowEmptySelection, onChange, options, selectedKeys, selectionMode ("single" | "multiple").

import { SurveySelect } from "@ada-cx/lovelace";
<SurveySelect
  aria-label="What did we help with?"
  selectionMode="multiple"
  options={[{ label: "Orders" }, { label: "Billing" }, { label: "Returns" }]}
/>;

Feedback and status

Components that report what the system is doing.

The tinted full-width strip that reports a condition, such as an outage, a lost connection, or a failed send. It carries no control, because only the state that raised the condition takes the banner down. It is presentational and owns no live region, so it announces nothing on its own. Put it in a BannerContainer. Key props: status ("success" | "warning" | "error"), children.

import { Banner } from "@ada-cx/lovelace";
<Banner status="error">Your network appears to be offline.</Banner>;

BannerContainer

Announces and animates one Banner. It owns the live region and mounts it empty, so a banner that arrives is a change the screen reader reports. error interrupts as an assertive alert. Any other status waits its turn as a polite status. The container clips the banner’s travel, so you need no overflow rule of your own. Mount it for as long as the surface exists. It never queues and never times out, and it holds one banner at a time, so pick the condition to show before you hand it over. Key props: children, occurrence.

Change occurrence whenever the reader must hear the banner again: the same condition raised a second time with the same wording, a different condition taking the slot, or a change of status. A change hides the live region for a frame and reveals it, which is what makes wording the reader has already heard read out again. Leave it alone to reword the banner, and the live region reports the new text on its own.

import { Banner, BannerContainer } from "@ada-cx/lovelace";
<BannerContainer occurrence={`offline:${attempt}`}>
  {isOffline ? (
    <Banner status="error">Your network appears to be offline.</Banner>
  ) : null}
</BannerContainer>;

Spinner

A loading spinner for inline or region loading states. Key props: size ("sm" | "lg"), background ("default" | "accent"), label.

import { Spinner } from "@ada-cx/lovelace";
<Spinner size="lg" label="Loading" />;

ThinkingShimmer

An animated shimmer label shown while the AI Agent generates a reply. Key props: label.

import { ThinkingShimmer } from "@ada-cx/lovelace";
<ThinkingShimmer label="Thinking" />;

Toast

The floating card that ToastContainer renders. It sits above the transcript on a neutral background, so a passing event does not look like the tinted strip a lasting condition uses. It carries no live region of its own, so it announces nothing when you render it alone. Use it directly only inside a container that owns the announcement. Key props: children, dismissDisabled, dismissLabel, icon, messageProps, onDismiss, status ("success" | "warning" | "error" | "custom" | "loading").

Set icon to supply the glyph for status="custom". The loading status shows a spinner and renders no dismiss button.

import { Toast } from "@ada-cx/lovelace";
<Toast status="success" onDismiss={() => setShown(false)}>
  Transcript sent
</Toast>;

ToastContainer

Shows the toasts on a queue as a labelled landmark region. The container owns announcement, the card surface, and the motion. It names the dismiss button in the reader’s own language. It keeps the region reachable with F6. The container shows no toast while a modal overlay is open, and shows the queue again after the overlay closes. Create one queue for each surface.

You own the clock. Decide which toasts exist, how long each one lives, and what a dismiss press means. Put a key in exiting to start that card’s travel off the stack, and keep the card on the queue until onExited reports it. Key props: aria-label, exiting, onDismiss, onExited, queue.

Hold your countdowns for two cases the reader cannot read through. A modal overlay hides the stack, so a countdown that runs on expires a card the reader never saw. The useHasOpenOverlay hook reports whether one is open. Keyboard focus inside the stack is the reader asking for more time, which is the only extension a card that dismisses itself offers. Listen for focusin and focusout on the container, and hold for as long as focus stays. The example below holds for the overlay; hold for focus the same way.

Each queue entry takes { message, status?, icon? }. The status accepts "success", "warning", "error", "custom", and "loading", and defaults to "success". Set icon to supply the glyph for status: "custom". A loading toast renders no dismiss button, so close or replace it from the code that queued it.

import { ToastContainer, ToastQueue, useHasOpenOverlay } from "@ada-cx/lovelace";
import type { ToastItem } from "@ada-cx/lovelace";
import { useCallback, useEffect, useRef, useState } from "react";
type Timer = { id: number | null; remainingMs: number; startedAt: number };
const toasts = new ToastQueue<ToastItem>();
const TIMEOUT_MS = 5000;
function Toasts() {
  const [exiting, setExiting] = useState<ReadonlySet<string>>(new Set());
  const timers = useRef(new Map<string, Timer>());
  const hasOpenOverlay = useHasOpenOverlay();
  const startExit = useCallback((key: string) => {
    window.clearTimeout(timers.current.get(key)?.id ?? undefined);
    timers.current.delete(key);
    setExiting((current) => new Set(current).add(key));
  }, []);
  const finishExit = useCallback((key: string) => {
    setExiting((current) => {
      const next = new Set(current);
      next.delete(key);
      return next;
    });
    toasts.close(key);
  }, []);
  const arm = useCallback(
    (key: string) => {
      const timer = timers.current.get(key);
      if (!timer) return;
      timer.startedAt = Date.now();
      timer.id = window.setTimeout(() => startExit(key), timer.remainingMs);
    },
    [startExit],
  );
  useEffect(() => {
    for (const [key, timer] of timers.current) {
      if (hasOpenOverlay && timer.id !== null) {
        window.clearTimeout(timer.id);
        timer.id = null;
        timer.remainingMs -= Date.now() - timer.startedAt;
      } else if (!hasOpenOverlay && timer.id === null) {
        arm(key);
      }
    }
  }, [hasOpenOverlay, arm]);
  const send = () => {
    const key = toasts.add({ message: "Transcript sent", status: "success" });
    timers.current.set(key, { id: null, remainingMs: TIMEOUT_MS, startedAt: 0 });
    if (!hasOpenOverlay) {
      arm(key);
    }
  };
  return (
    <>
      <button onClick={send}>Send transcript</button>
      <ToastContainer
        queue={toasts}
        exiting={exiting}
        onExited={finishExit}
        onDismiss={startExit}
      />
    </>
  );
}

TypingIndicator

An animated three-dot bubble shown while a human agent types. Use ThinkingShimmer for AI generation instead. Key props: aria-label, aria-live.

import { TypingIndicator } from "@ada-cx/lovelace";
<TypingIndicator aria-label="Agent is typing" />;

Overlays and menus

Modal and floating surfaces. The overlay components own presentation (scrim, focus trap, dismissal); the content components own layout.

BubbleOverlay

A non-dimming modal bubble near the bottom edge; the chat behind it stays visible. Key props: isOpen, onOpenChange, isDismissable, aria-label.

import { BubbleOverlay } from "@ada-cx/lovelace";
import { useState } from "react";
function QuickHelp() {
  const [open, setOpen] = useState(false);
  return (
    <BubbleOverlay
      isOpen={open}
      onOpenChange={setOpen}
      isDismissable
      aria-label="Quick help"
    >
      <p>A non-dimming bubble near the bottom edge.</p>
    </BubbleOverlay>
  );
}

DialogOverlay

A centered modal dialog presentation with a scrim. Key props: isOpen, onOpenChange, isDismissable, role ("dialog" | "alertdialog").

import { Button, Dialog, DialogOverlay } from "@ada-cx/lovelace";
import { useState } from "react";
function ConfirmDelete() {
  const [open, setOpen] = useState(false);
  return (
    <DialogOverlay isOpen={open} onOpenChange={setOpen} isDismissable>
      <Dialog>
        <Dialog.Content>
          <Dialog.Title>A modal dialog</Dialog.Title>
          <Dialog.Body>
            Presented by DialogOverlay with a scrim and a focus trap.
          </Dialog.Body>
        </Dialog.Content>
        <Dialog.Actions>
          <Button onPress={() => setOpen(false)}>Done</Button>
        </Dialog.Actions>
      </Dialog>
    </DialogOverlay>
  );
}

FullscreenOverlay

A modal surface that fills the window. Key props: isOpen, onOpenChange, isDismissable.

import { Button, FullscreenOverlay } from "@ada-cx/lovelace";
import { useState } from "react";
function FullscreenDemo() {
  const [open, setOpen] = useState(false);
  return (
    <FullscreenOverlay isOpen={open} onOpenChange={setOpen} isDismissable>
      <p>A surface that fills the window.</p>
      <Button onPress={() => setOpen(false)}>Close</Button>
    </FullscreenOverlay>
  );
}

SheetOverlay

A dimming, slide-up modal bottom-sheet presentation. Key props: isOpen, onOpenChange, isDismissable, aria-label.

import { Sheet, SheetOverlay } from "@ada-cx/lovelace";
import { useState } from "react";
function TranscriptSheet() {
  const [open, setOpen] = useState(false);
  return (
    <SheetOverlay isOpen={open} onOpenChange={setOpen} isDismissable>
      <Sheet>
        <Sheet.Header
          title="A bottom sheet"
          showClose
          onClose={() => setOpen(false)}
        />
        <Sheet.Body>
          <p>Presented by SheetOverlay: it dims and slides up.</p>
        </Sheet.Body>
      </Sheet>
    </SheetOverlay>
  );
}

Dialog

Dialog content: icon, title, body, and action buttons. Compound: Dialog.Icon, Dialog.Content, Dialog.Title, Dialog.Body, Dialog.Actions. Wrap in DialogOverlay for the modal presentation.

import { Button, Dialog } from "@ada-cx/lovelace";
<Dialog>
  <Dialog.Icon intent="warning" />
  <Dialog.Content>
    <Dialog.Title>Delete conversation?</Dialog.Title>
    <Dialog.Body>This can't be undone.</Dialog.Body>
  </Dialog.Content>
  <Dialog.Actions>
    <Button destructive>Delete</Button>
    <Button variant="tertiary">Cancel</Button>
  </Dialog.Actions>
</Dialog>;

Sheet

Bottom-sheet content. Compound: Sheet.Header, Sheet.Body, Sheet.Actions. Wrap in SheetOverlay for the modal presentation.

import { Button, Sheet } from "@ada-cx/lovelace";
<Sheet>
  <Sheet.Header title="Email transcript" showClose onClose={close} />
  <Sheet.Body>
    <p>Enter an email address to receive a copy of this conversation.</p>
  </Sheet.Body>
  <Sheet.Actions>
    <Button>Send</Button>
  </Sheet.Actions>
</Sheet>;

Menu is a role="menu" collection with arrow-key navigation and typeahead; MenuItem is one row (compound: MenuItem.Label, plus MenuItem.Checkbox / MenuItem.Radio / MenuItem.Toggle for a selection indicator). Row content is ordered by child position around the label. Key props — Menu: aria-label, onAction, children; MenuItem: children.

import { Menu, MenuItem } from "@ada-cx/lovelace";
<Menu aria-label="Conversation actions" onAction={handleAction}>
  <MenuItem>
    <MenuItem.Label>Email transcript</MenuItem.Label>
  </MenuItem>
  <MenuItem>
    <MenuItem.Label>Mute sounds</MenuItem.Label>
  </MenuItem>
  <MenuItem>
    <MenuItem.Label>End chat</MenuItem.Label>
  </MenuItem>
</Menu>;

Tooltip is an inverse-surface tooltip with a directional arrow; TooltipTrigger (re-exported from React Aria Components) associates it with a focusable trigger. Key props — Tooltip: placement ("top" | "bottom" | "left" | "right"), children; TooltipTrigger: delay, children.

import { Button, Tooltip, TooltipTrigger } from "@ada-cx/lovelace";
<TooltipTrigger delay={0}>
  <Button variant="secondary" size="sm">
    Hover me
  </Button>
  <Tooltip placement="top">Tooltips point at their trigger</Tooltip>
</TooltipTrigger>;

Primitives

Low-level building blocks the other components compose.

Avatar

A circular avatar bubble holding initials, an Icon, or an Image. Key props: size ("sm" | "md" | "lg" | "xl"), label (or aria-hidden), showAvatar, children.

import { Avatar, Image } from "@ada-cx/lovelace";
<>
  <Avatar size="lg" label="Ada AI Agent">
    A
  </Avatar>
  <Avatar size="md" label="Support agent">
    <Image src="https://example.com/agent.jpg" alt="" />
  </Avatar>
</>;

AvatarPlaceholder

An empty avatar bubble for loading or anonymous states. Key props: size.

import { AvatarPlaceholder } from "@ada-cx/lovelace";
<AvatarPlaceholder size="md" />;

Icon

Wraps one icon glyph and standardizes its size and accessible name. Key props: label, children.

import { Icon, SendFill } from "@ada-cx/lovelace";
<Icon label="Send">
  <SendFill />
</Icon>;

Image

An image with load-state tracking and a fallback slot. Key props: src, alt (required), fallback, onLoadingStatusChange.

import { Image } from "@ada-cx/lovelace";
<Image src="https://example.com/photo.jpg" alt="Order photo" />;

Icon glyphs

The package also exports a set of ready-made glyph components, including ArrowDown, Checkmark, ChevronLeft, CloudUpload, Email, Paperclip, SendFill, ThumbsDown, and ThumbsUp. Each glyph wraps itself for correct sizing, so you can pass one directly wherever a component asks for an icon:

import { IconButton, SendFill } from "@ada-cx/lovelace";
<IconButton label="Send message" onPress={send}>
  <SendFill />
</IconButton>;

The full glyph list is in the package’s TypeScript declarations, and every glyph renders in the live component gallery.