Section

A report or detail page is a run of titled blocks: Delivery, Engagement, Bounces. Section is one of them, a <section> labelled by its title, with an optional description under the title and actions at the end of the header row. The title and description use the type of FieldLegend and FieldDescription, so a form's sections and a report's sections match. Inside a form, keep using FieldSet and FieldLegend.

Usage

import { Button } from '@/components/ui/button';
import { Section } from '@/components/ui/section';
import { SegmentedBar } from '@/components/ui/segmented-bar';

<Section
  title="Delivery"
  description="Spring list · 1,204 recipients"
  actions={<Button variant="outline">Export</Button>}
>
  <SegmentedBar segments={outcomes} legend />
</Section>

A Section draws no fill or border and sets its children in a column with a 16px gap. Put Cards or a Stat strip inside when a block needs a frame. The actions sit on the title's row, and the description runs under both, so a long description never pushes them down. On a phone they move under the description.

Heading levels

The title is an h2 by default. Pass as="h3" or as="h4" for a section nested under another, so the page's outline stays in order. The level changes the element and not the look, so a nested title is the same size as the one above it.

Props

Section takes every <section> attribute except title, plus these.

Accessibility

• It renders a <section> with aria-labelledby pointing at its title, so it is a region landmark that is named by the heading. A page with many sections gives a screen reader a list of regions to jump between, so give each one a distinct title.
• The title is a real heading, an h2 unless you pass as. Pass as="h3" or as="h4" for a nested section and keep the levels in order. The page's own h1 comes from Page header or your own heading.
• A title that is a node and not text still names the section, but the name is read from its text content, so keep it to words.
• Section has no interaction, motion, or color of its own. The description is text-fg-muted, and its contrast on your surface is not checked here.

When to use something else

• Card when the block needs a frame, a fill, or an edge. Section is the heading and layout around a block, and Card is the surface. They combine, with Cards inside a Section.
• Accordion or Collapsible when the reader should be able to fold the block away. A Section is always open.
• Page header for the title of the page or panel itself.
• FieldSet and FieldLegend from Field for a group of controls inside a form, where the legend names the group for assistive tech.

Install

shadcn add @gesso/section