Description

The <Description> component is a short piece of supporting text that pairs with a <Title> in container surfaces or with a <TextValue> in selection items.

Anatomy

A description is a single text element with no parts of its own.

Appearance

<Description> carries no styling of its own. Its appearance comes entirely from the surrounding container or selection item, which keeps the look consistent across panels, dialogs, menus, and selects. Pair it with <Title> in containers, or with <TextValue> in selection items.

Styling is inferred automatically from the surrounding context. See Slot-Driven Composition for how this works.

Usage

Reach for <Description> whenever a <Title> or <TextValue> partner benefits from a one-line explanation. For paragraph text or body copy that isn't paired with a heading or label, use <Text> instead.

Paired with a Title

Use this inside container surfaces (<Panel>, <Dialog>, <EmptyState>) to explain a title. The <Description> sits directly below the <Title>.

import { Description, Panel, Title } from '@marigold/components';export default () => (  <Panel>    <Panel.Header>      <Title>Storage usage</Title>      <Description>        42% of your storage quota is currently in use. Upgrade your plan to        unlock more space.      </Description>    </Panel.Header>  </Panel>);

Paired with a TextValue

Use this inside selection items (<Select.Option>, <Menu.Item>, <ListBox.Item>) to add a help line below the item label. Screen readers announce the label as the option's accessible name and the <Description> as supporting content.

import { Description, Select, TextValue } from '@marigold/components';export default () => (  <Select label="Plan" defaultValue="pro" width={64}>    <Select.Option id="free">      <TextValue>Free</TextValue>      <Description>Up to 3 projects</Description>    </Select.Option>    <Select.Option id="pro">      <TextValue>Pro</TextValue>      <Description>Unlimited projects and priority support</Description>    </Select.Option>    <Select.Option id="enterprise">      <TextValue>Enterprise</TextValue>      <Description>SSO, audit logs, custom contracts</Description>    </Select.Option>  </Select>);

Accessibility

<Description> becomes the accessible description of the element it pairs with. Screen readers announce the accessible name first (the heading or label), then the description after a short pause as supporting context.

The wiring is automatic. The partner element generates an id for the description and points its aria-describedby at that id, so you never need to set the attribute manually.

Two practical consequences follow from this:

• One description per region. When multiple aria-describedby targets exist, browsers concatenate them into a single announced string. Splitting supporting content across two descriptions removes the natural pause and produces one long, hard-to-scan announcement.
• Keep it concise. The description is read every time the partner receives focus or hover, so verbose copy quickly becomes noise.

A description used without a partner that registers a description slot renders as plain text without an aria-describedby link. It contributes to the visible content but has no programmatic relationship to anything else.

Props

Description

Alternative components

• Text: Use for paragraph text, body copy, and inline text that isn't paired with a Title or label.
• Title: The heading partner for Description in container surfaces.
• TextValue: The label partner for Description in selection items.