# Separator

A horizontal or vertical line between pieces of content.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Separator } from "@/components/ui/separator"
import { VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"
import { leading, text, width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  root: { width: "100%", maxWidth: width.sm, fontSize: text.sm, lineHeight: leading.sm },
  title: { fontWeight: 500, lineHeight: 1 },
})

export default function SeparatorDemo() {
  return (
    <VStack gap={4} xstyle={styles.root}>
      <VStack gap={1.5}>
        <div {...stylex.props(styles.title)}>arene</div>
        <Text render={<div />} tone="muted">
          An opinionated React design system
        </Text>
      </VStack>
      <Separator />
      <div>Components on Base UI and StyleX, distributed by copy and paste.</div>
    </VStack>
  )
}
```

## Installation

**Command**

```bash
npx shadcn@latest add @arene/separator
```

Needs the [arene setup](https://www.arene.style/docs/installation) first.

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @base-ui/react @stylexjs/stylex clsx
   ```

2. Set up the token layer and the StyleX compiler, if you have not already. See
   [Installation](https://www.arene.style/docs/installation).

3. Paste this source into the file named in its title.

   ```tsx title="components/ui/separator.tsx"
   import { Separator as SeparatorPrimitive } from "@base-ui/react/separator"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"

   import { color } from "@/theme/tokens.stylex"

   const styles = stylex.create({
     base: {
       flexShrink: 0,
       backgroundColor: color.border,
     },
   })

   const orientations = stylex.create({
     horizontal: { width: "100%", height: 1 },
     vertical: { width: 1, alignSelf: "stretch" },
   })

   const separatorStyles = { base: styles.base, orientations }

   type SeparatorOrientation = keyof typeof orientations

   type SeparatorProps = Omit<SeparatorPrimitive.Props, "className"> & {
     xstyle?: StyleXStyles
     className?: string
   }

   function Separator({ orientation = "horizontal", xstyle, className, ...props }: SeparatorProps) {
     const sx = stylex.props(styles.base, orientations[orientation] ?? orientations.horizontal, xstyle)

     return (
       <SeparatorPrimitive
         data-slot="separator"
         orientation={orientation}
         {...sx}
         {...props}
         className={clsx(sx.className, className)}
       />
     )
   }

   export { Separator, separatorStyles, type SeparatorOrientation }
   ```

4. Change the `@/` imports if your project uses different aliases.

## Usage

```tsx
import { Separator } from "@/components/ui/separator"
```

```tsx
<Separator />
```

## Vertical

`orientation="vertical"` draws the line from top to bottom. It stretches to the
height of the flex row it sits in.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Separator } from "@/components/ui/separator"
import { HStack } from "@/components/ui/stack"
import { leading, space, text } from "@/theme/tokens.stylex"

const styles = stylex.create({
  root: { height: space.s5, fontSize: text.sm, lineHeight: leading.sm },
})

export default function SeparatorVertical() {
  return (
    <HStack gap={4} align="center" xstyle={styles.root}>
      <div>Blog</div>
      <Separator orientation="vertical" />
      <div>Docs</div>
      <Separator orientation="vertical" />
      <div>Source</div>
    </HStack>
  )
}
```

> **Note**
>
> A vertical separator has no height of its own. Outside a flex container, or in
> a row aligned by anything other than `stretch`, give it one through `xstyle`.

## Menu

Vertical separators divide a row of menu entries that each carry a description.

```tsx
import { Separator } from "@/components/ui/separator"
import { HStack, VStack } from "@/components/ui/stack"
import { Text, textStyles } from "@/components/ui/text"

export default function SeparatorMenu() {
  return (
    <HStack gap={4} align="center" xstyle={textStyles.sizes.sm}>
      <VStack gap={1}>
        <Text weight="medium">Builds</Text>
        <Text size="xs" tone="muted">
          Runs and logs
        </Text>
      </VStack>
      <Separator orientation="vertical" />
      <VStack gap={1}>
        <Text weight="medium">Members</Text>
        <Text size="xs" tone="muted">
          People and roles
        </Text>
      </VStack>
      <Separator orientation="vertical" />
      <VStack gap={1}>
        <Text weight="medium">Docs</Text>
        <Text size="xs" tone="muted">
          Guides and API
        </Text>
      </VStack>
    </HStack>
  )
}
```

## List

Horizontal separators divide the rows of a list.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Separator } from "@/components/ui/separator"
import { HStack, VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"
import { leading, text, width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  root: { width: "100%", maxWidth: width.sm, fontSize: text.sm, lineHeight: leading.sm },
})

export default function SeparatorList() {
  return (
    <VStack gap={2} xstyle={styles.root}>
      <HStack render={<dl />} justify="between" align="center">
        <dt>Version</dt>
        <Text render={<dd />} tone="muted">
          2.4.0
        </Text>
      </HStack>
      <Separator />
      <HStack render={<dl />} justify="between" align="center">
        <dt>Released</dt>
        <Text render={<dd />} tone="muted">
          May 12, 2025
        </Text>
      </HStack>
      <Separator />
      <HStack render={<dl />} justify="between" align="center">
        <dt>License</dt>
        <Text render={<dd />} tone="muted">
          MIT
        </Text>
      </HStack>
    </VStack>
  )
}
```

## API reference

Pass `render` to replace a part's element or compose it with another component.

`Separator` wraps the Base UI `Separator` and accepts its props. See the
[Base UI reference](https://base-ui.com/react/components/separator). It renders
a `<div role="separator">` with `aria-orientation` set from the prop.

### Separator

| Prop          | Type                         | Default        |
| ------------- | ---------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
| `xstyle`      | `StyleXStyles`               | —              |
| `className`   | `string`                     | —              |

### separatorStyles

The style maps behind the component. Spread them onto any element.

| Key            | What it is                                                    |
| -------------- | ------------------------------------------------------------- |
| `base`         | The fill and `flex-shrink: 0`                                 |
| `orientations` | `horizontal` and `vertical`: the 1px thickness and the length |

### Data attributes

| Attribute               | On            | Effect                               |
| ----------------------- | ------------- | ------------------------------------ |
| `data-slot="separator"` | the separator | Targets the rule from a parent       |
| `data-orientation`      | the separator | Base UI writes it from `orientation` |
