# Separator

Draws a rule between groups of content.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Separator.tsx)

Figma: [Elements/Divider](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3269)

## Overview

Separator renders a 1px rule between thematic groups, such as menu sections or toolbar clusters. A horizontal rule sits centered in a 16px row. With `children`, it centers a short label between two rules, such as `or` between two ways to sign in.

## Examples

### Basic

```tsx
import { Separator, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <span>Above</span>
      <Separator />
      <span>Below</span>
    </div>
  )
}

namespace styles {
  export const stack = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '12',
    maxWidth: '16rem !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Separator/Basic.tsx)

### Orientation

Set `orientation` to `horizontal` (default) or `vertical`.

```tsx
import { Separator, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      <span>Left</span>
      <Separator orientation="vertical" />
      <span>Right</span>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12', height: '24' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Separator/Orientation.tsx)

### Label

Pass a short label as `children` to join two alternatives. A vertical separator ignores it.

```tsx
import { Button, Separator, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.stack()}>
      <Button variant="secondary">Continue with passkey</Button>
      <Separator>or</Separator>
      <Button variant="secondary">Continue with email</Button>
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '16', width: '320' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Separator/Label.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Separator } from '@tempoxyz/ds'

<Separator />
```

## Guidelines

### When to Use

* Divide groups that spacing alone does not separate, such as line items and a total.
* Divide clusters of toolbar controls, with `orientation="vertical"`.
* Join two alternatives with a label, such as `or` between two ways to sign in.

### When Not to Use

* Use [ListGroup](/docs/components/list-group) or [Table](/docs/components/table) for lists of records. They draw their own dividers.
* Use `SidebarMenu.Group` in a [SidebarMenu](/docs/components/sidebar-menu) and `Menu.Separator` in a [Menu](/docs/components/menu).

### Try Space First

A larger gap separates most groups, such as a [Stack](/docs/components/stack) with `gap="24"`. Add a separator only if the groups still run together, or one row must stand apart, such as a total.

**Do:** Separate the total from the line items above it.

```tsx
/**
 * Do example for "Try Space First" on the Separator page.
 * Separate the total from the line items above it.
 * @module
 */
import { Separator, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.summary()}>
      <div {...styles.row()}>
        <span>Amount</span>
        <span>250.00 USDC</span>
      </div>
      <div {...styles.row()}>
        <span>Network fee</span>
        <span>0.01 USDC</span>
      </div>
      <Separator />
      <div {...styles.total()}>
        <span>Total</span>
        <span>250.01 USDC</span>
      </div>
    </div>
  )
}

namespace styles {
  export const row = style({
    color: 'content.secondary',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2',
  })

  export const summary = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '12',
    width: '100% !custom',
  })

  export const total = style({
    color: 'content.primary',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2Strong',
  })
}
```

**Don't:** Rule off every row.

```tsx
/** Don't example for "Try Space First" on the Separator page. Don't rule off every row. @module */
import { Separator, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.summary()}>
      <Separator />
      <div {...styles.row()}>
        <span>Amount</span>
        <span>250.00 USDC</span>
      </div>
      <Separator />
      <div {...styles.row()}>
        <span>Network fee</span>
        <span>0.01 USDC</span>
      </div>
      <Separator />
      <div {...styles.total()}>
        <span>Total</span>
        <span>250.01 USDC</span>
      </div>
      <Separator />
    </div>
  )
}

namespace styles {
  export const row = style({
    color: 'content.secondary',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2',
  })

  export const summary = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '12',
    width: '100% !custom',
  })

  export const total = style({
    color: 'content.primary',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2Strong',
  })
}
```

### Keep Rules Inside Containers

The edge of a [Surface](/docs/components/surface) or popup already ends the group.

**Do:** Place separators only between groups.

```tsx
/**
 * Do example for "Keep Rules Inside Containers" on the Separator page.
 * Place separators only between groups.
 * @module
 */
import { Separator, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface size="medium" {...styles.summary()}>
        <div {...styles.row()}>
          <span>Amount</span>
          <span>250.00 USDC</span>
        </div>
        <div {...styles.row()}>
          <span>Network fee</span>
          <span>0.01 USDC</span>
        </div>
        <Separator />
        <div {...styles.total()}>
          <span>Total</span>
          <span>250.01 USDC</span>
        </div>
      </Surface>
    </div>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })

  export const row = style({
    color: 'content.secondary',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2',
  })

  export const summary = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })

  export const total = style({
    color: 'content.primary',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2Strong',
  })
}
```

**Don't:** Place a separator at the top or bottom edge of a Surface.

```tsx
/**
 * Don't example for "Keep Rules Inside Containers" on the Separator page.
 * Don't place a separator at the top or bottom edge of a Surface.
 * @module
 */
import { Separator, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface size="medium" {...styles.summary()}>
        <Separator />
        <div {...styles.row()}>
          <span>Amount</span>
          <span>250.00 USDC</span>
        </div>
        <div {...styles.row()}>
          <span>Network fee</span>
          <span>0.01 USDC</span>
        </div>
        <Separator />
        <div {...styles.total()}>
          <span>Total</span>
          <span>250.01 USDC</span>
        </div>
        <Separator />
      </Surface>
    </div>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })

  export const row = style({
    color: 'content.secondary',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2',
  })

  export const summary = style({ display: 'flex', flexDirection: 'column', rowGap: '12' })

  export const total = style({
    color: 'content.primary',
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2Strong',
  })
}
```

## Accessibility

### Semantics

* **Element (separator):** Exposed as a boundary between groups. Some screen readers announce "separator", and others skip it.
* **Orientation (aria-orientation):** Follows `orientation`. A vertical separator stretches to the height of its row, at least 1em.
* **Label (div):** A separator hides its children from screen readers, so a labeled one renders a `div` without the role. Screen readers read the label in place, and the rules stay hidden.
* **No Focus:** Not focusable, with no keyboard behavior.

### Your Responsibilities

* **Use Headings for Structure (SC 1.3.1):** A separator does not [name the group](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) that follows it.
* **Separate Meaningful Groups:** Use it only between meaningful groups. Draw a decorative line with a CSS border.

## Related

[Stack](/docs/components/stack)

Use for spacing groups apart.

[ListGroup](/docs/components/list-group)

Use for divided lists.

[Menu](/docs/components/menu)

Use for separators between menu groups.
