<!-- Protocore Design System — Divider -->
# Divider

- **Category:** Layout (`layout`)
- **Slug:** `layout/divider`
- **Status:** stable
- **Platforms:** web, mobile
- **Import:** `import { Divider } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/layout/divider

> A 1px hairline separator, horizontal or vertical, with an optional centred mono label.

## When to use it

Use a `Divider` when a boundary needs to be **visible** — a rule that groups or separates content. When you only need empty space, use a `Spacer` or a `Stack` gap instead; an invisible gap shouldn't be a hairline. Mark a Divider `decorative` when it is purely visual and the grouping is already clear from structure, so it drops out of the accessibility tree. Note that `Section` with `surface` and `Panel` already draw their own edge hairlines — don't add a Divider on top of those seams.

## Mobile (React Native)

**Preview.** `@protocore/pds-mobile` ships the React Native sibling of **Divider**. It mirrors the web API where React Native allows; the package is a **preview** with no device-level QA yet, so pin it and expect small changes.

Import it from the mobile package (not `@protocore/pds`), inside a `<PdsProvider>` — there is no stylesheet, so `style` (a `ViewStyle`) replaces `className` and every value comes from the theme:

```tsx
import { Divider } from "@protocore/pds-mobile";
```

**Parity with web.** A hairline separator, horizontal or vertical, with an optional centred mono label.

- Uses `StyleSheet.hairlineWidth` for a true device-pixel rule (sanctioned for Divider in the conventions).
- The centred `label` is horizontal-only.

```tsx
<Divider label="OR" />
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `className` | `string` | no | — | — |
| `decorative` | `boolean` | no | `false` | Purely decorative — drops the separator role from the a11y tree. |
| `label` | `ReactNode` | no | — | Optional centred mono label (horizontal only), flanked by two rules. |
| `orientation` | `enum` | no | `horizontal` | Axis of the rule. |
| `style` | `CSSProperties` | no | — | — |

## Examples

### Basics

A horizontal `Divider` draws a single hairline between blocks. By default it carries the `separator` role for assistive tech.

```tsx
import { Divider, Stack, Text } from "@protocore/pds";

export default function DividerBasics() {
  return (
    <Stack gap={4}>
      <Text>Consensus reached at height 8,241,003.</Text>
      <Divider />
      <Text color="secondary">Finalized 14 blocks later.</Text>
    </Stack>
  );
}
```

### Labelled

Pass a `label` (horizontal only) to centre a mono caption between two rules — useful for marking a boundary like an epoch or a date break.

```tsx
import { Divider, Stack, Text } from "@protocore/pds";

export default function DividerLabelled() {
  return (
    <Stack gap={4}>
      <Text mono size="sm">
        block 8,241,003
      </Text>
      <Divider label="EPOCH 512" />
      <Text mono size="sm">
        block 8,241,004
      </Text>
    </Stack>
  );
}
```

## Do & don't

**Do**

- Use a Divider when the separation itself needs to be seen.
- Add a label to mark a semantic boundary like an epoch or a day.
- Set decorative when the rule is cosmetic and grouping is already obvious.

**Don't**

- Use a Divider where a Spacer or gap (plain empty space) is what you actually want.
- Stack Dividers next to a surface Section or Panel edge that already has a hairline.
- Pass a label to a vertical Divider — labels render on horizontal rules only.

## Accessibility

**Notes**

- Defaults to `role="separator"` with `aria-orientation` reflecting the axis.
- `decorative` swaps in `role="none"` and `aria-hidden`, removing it from the a11y tree.
- A labelled Divider still exposes the separator role; the label is visible text, not the accessible boundary.

## Related

`spacer`, `stack`, `section`, `panel`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/