# Section Heading

A heading with an optional description and action that opens a group inside a page, a card or a settings form.

```tsx
import { PlusIcon } from "lucide-react"
import { Button } from "@zenoxai/ui/components/button"
import { SectionHeading } from "@zenoxai/ui/patterns/section-heading"

function SectionHeadingDemo() {
  return (
    <SectionHeading
      className="w-full max-w-lg"
      title="API keys"
      description="Keys let scripts and integrations call the Zenox API."
      action={
        <Button variant="outline" size="sm">
          <PlusIcon data-icon="inline-start" />
          New key
        </Button>
      }
    />
  )
}
```

## Usage

```tsx
import { Button } from "@zenoxai/ui/components/button"
import { SectionHeading } from "@zenoxai/ui/patterns/section-heading"

export function ApiKeysHeading() {
  return (
    <SectionHeading
      title="API keys"
      description="Keys let scripts and integrations call the Zenox API."
      action={<Button size="sm">New key</Button>}
    />
  )
}
```

Use a section heading to split a long page or a settings form into groups the user can scan.
The title is set at the card-title step (18px, semibold); the description is one line in the
secondary text color; the action sits on the right and stays at its own width when the title
wraps.

Use something else when:

- The heading is the title of the page. Use [PageHeader](/patterns/page-header).
- The group is a self-contained panel with a border. Use a [Card](/components/card) and its
  `CardTitle`.

## In a settings card

A settings card often holds more than one group. Leave out `CardHeader`, open each group with
a section heading inside `CardContent`, wrap each group in a `<section>` and separate the groups
with a [Separator](/components/separator).

Do not put a section heading under a `CardTitle`: the section heading is the larger of the two
and would read as the parent.

```tsx
import { Button } from "@zenoxai/ui/components/button"
import { Card, CardContent } from "@zenoxai/ui/components/card"
import { Field, FieldContent, FieldDescription, FieldGroup, FieldLabel } from "@zenoxai/ui/components/field"
import { Separator } from "@zenoxai/ui/components/separator"
import { Switch } from "@zenoxai/ui/components/switch"
import { SectionHeading } from "@zenoxai/ui/patterns/section-heading"

function SectionHeadingInSettingsCard() {
  return (
    <Card className="w-full max-w-lg">
      <CardContent className="grid gap-6">
        <section className="grid gap-4">
          <SectionHeading
            title="Email notifications"
            description="Sent to the analysts on the on-call rota."
          />
          <FieldGroup>
            <Field orientation="horizontal">
              <FieldContent>
                <FieldLabel htmlFor="email-critical">
                  Critical alerts
                </FieldLabel>
                <FieldDescription>Sent at once, at any hour.</FieldDescription>
              </FieldContent>
              <Switch id="email-critical" defaultChecked />
            </Field>
            <Field orientation="horizontal">
              <FieldContent>
                <FieldLabel htmlFor="email-digest">Daily digest</FieldLabel>
                <FieldDescription>
                  A summary of the last 24 hours, at 08:00.
                </FieldDescription>
              </FieldContent>
              <Switch id="email-digest" />
            </Field>
          </FieldGroup>
        </section>
        <Separator />
        <section className="grid gap-4">
          <SectionHeading
            title="Webhooks"
            description="Post every new alert to an external endpoint."
            action={
              <Button variant="outline" size="sm">
                Add webhook
              </Button>
            }
          />
          <p className="text-sm text-text-secondary">No webhooks yet.</p>
        </section>
      </CardContent>
    </Card>
  )
}
```

## Accessibility

- `SectionHeading` renders an `<h2>` by default, one step below the page `<h1>`. Set `as` to
  keep the outline in order when the section sits under another `<h2>`: `as="h3"`, or `as="h4"`
  one level further down.
- The action is outside the heading element, so the heading's accessible name is the title
  alone. Give the action a label that makes sense on its own ("New key", not "New").

## API reference

`import { ... } from "@zenoxai/ui/patterns/section-heading"`

### SectionHeading

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| action | `ReactNode` |  | Right-aligned slot, usually a small button. |
| as | `"h2" \| "h3" \| "h4"` | `h2` | Heading level. Defaults to h2, one step below the page <h1>. |
| description | `ReactNode` |  | One line under the title. |
| title (required) | `ReactNode` |  |  |