SectionCard

Usage examples

import { useState } from 'react';
import { Button } from '@rookcom/monarch-react';
import { SectionCard, type SectionCardState } from '@rookcom/monarch-react/patterns';

function StatesDemo() {
  const [state, setState] = useState<SectionCardState>('loading');
  return (
    <div style={{ display: 'grid', gap: '0.75rem', width: '100%' }}>
      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem' }}>
        {(['ready', 'loading', 'empty', 'error'] as const).map((s) => (
          <Button key={s} size="xs" aria-pressed={state === s} onClick={() => setState(s)}>
            {s}
          </Button>
        ))}
      </div>
      <SectionCard
        title="Upcoming invoices"
        state={state}
        emptyDescription="Invoices you schedule appear here."
        errorDescription="Check your connection and try again."
        onRetry={() => setState('ready')}
      >
        <p style={{ margin: 0 }}>3 invoices due this month.</p>
      </SectionCard>
    </div>
  );
}

<StatesDemo />

import { Button } from '@rookcom/monarch-react';
import { SectionCard } from '@rookcom/monarch-react/patterns';

<div style={{ display: 'grid', gap: '1rem', width: '100%' }}>
  <SectionCard title="Activity" collapsible defaultOpen={false}>
    <p style={{ margin: 0 }}>Ada changed the status to Active.</p>
  </SectionCard>
  <SectionCard
    title="Delete this project"
    tone="danger"
    description="Deleting the project removes its tasks and files."
    actions={
      <Button variant="danger" size="sm">
        Delete project
      </Button>
    }
  />
</div>

Purpose

Puts one section of a dashboard, detail or settings page in a card: a SectionHeader (title, description, meta, actions, "View all" link), the body, an optional footer, and the loading, empty and error states every data-backed section needs. It can be collapsible.

Design principles

• Always a labelled region: the heading names the <section>, so landmark navigation lists it.
• One state at a time: the body shows the content, a skeleton, an empty state or an error, never two.
• Refreshing is not loading: busy keeps the content and shows a spinner by the title.
• The heading level follows the page outline (headingLevel), never the visual size.

API reference

import { SectionCard } from '@rookcom/monarch-react/patterns';

Renders <section aria-labelledby> and forwards its ref; native attributes pass through.

The header is a SectionHeader without children; title, description, meta, actions, link and headingLevel are passed to it.

States reuse LoadingState, EmptyState and ErrorState (compact). Pass empty for a custom empty state with actions.

Exported from @rookcom/monarch-react/patterns.

Generated from the TypeScript declarations of packages/react/src/components/layout/section-card.

Properties

Variants

States

Interaction behaviour

• Header actions and the "View all" link behave as usual.
• With collapsible, activating the title toggles the body (uncontrolled with defaultOpen, controlled with open and onOpenChange).
• The error state’s retry button calls onRetry; show retrying while it runs.

Keyboard support

Accessibility

Role

region (section with aria-labelledby)

Accessible name

The section title.

• The heading labels the section; set headingId to point other elements at it.
• The collapsible toggle follows the APG disclosure pattern: a button inside the heading with aria-expanded and aria-controls.
• The icon is decorative and hidden from assistive technology.
• Loading and busy set aria-busy; the loading label is announced politely.

Responsive behaviour

• Header actions wrap under the title when space runs out (SectionHeader).
• Below 480px the header, body and footer padding tighten.
• The footer wraps its content and keeps it end-aligned.

Theme support

• Surface, borders, footer and danger colours use Monarch semantic tokens, so every theme applies.
• The chevron rotation is instant with reduced motion.

Do and don't

Related components

• SectionHeader: The header it renders; use it alone for unboxed sections.
• Card: A plain surface without a title or states.
• SettingsSection: Settings rows with Save/Discard.
• EmptyState: The default empty body; pass your own in empty.
• ErrorState: The error body.
• LoadingState: The loading body.

Dependencies

Testing coverage

• Is a region labelled by its heading, with icon, actions, link, body and footer; ref forwarding; Tab order.
• Shows loading (busy, announced), empty (default and custom) and error (retry) states instead of the children.
• busy keeps the content and marks the section busy.
• Collapsible uncontrolled: the title is a disclosure button; Enter and Space toggle the body and footer.
• Collapsible controlled with open, and defaultOpen={false}.
• Exposes tone and flush; honours headingLevel and headingId.
• Renders on the server.

Tests: packages/react/src/components/layout/section-card