---
layout: '@/layouts/Doc.astro'
title: Separator
---

import Example from '@/components/Example.astro'
import separatorStyle from '@webtui/css/components/separator.css?raw'
import boxStyle from '@webtui/css/utils/box.css?raw'

A horizontal or vertical separator

<Example
    stylesheets={[separatorStyle]}
    css={`
        body {
            display: flex;
            flex-direction: column;
        }
    `}
    html={`<p>The quick brown fox obliterates</p>
<div is-="separator"></div>
<p>the lazy dog</p>
`}
/>

## Import

```css
@import '@webtui/css/components/separator.css';
```

## Usage

```html
<!-- Horizontal -->
<div is-="separator"></div>
<div is-="separator" direction-="horizontal"></div>
<div is-="separator" direction-="x"></div>

<!-- Vertical -->
<div is-="separator" direction-="vertical"></div>
<div is-="separator" direction-="y"></div>
```

If `direction-` is not specified, separators are horizontal by default.

## Examples

### Vertical

<Example
    stylesheets={[separatorStyle]}
    css={`
        body {
            display: flex;
            flex-direction: row;
        }
    `}
    html={`<p>The lazy brown<br/>dog licks</p>
<div is-="separator" direction-="vertical"></div>
<p>the yucky<br/>fox</p>
`}
/>

### Caps

Use the `cap-` attribute to control how the ends of the separator behave

#### Bisecting Caps

`cap-="bisect"` extends the edges of the separator by `0.5ch` making it ideal to use alongside the `box-` utility

<Example
    stylesheets={[separatorStyle, boxStyle]}
    css={`
        body,
        .row {
            display: flex;
            flex-direction: row;
            flex: 1;
        }
        .column {
            display: flex;
            flex-direction: column;
            flex: 1;
        }
    `}
    html={`
<div class="column">
    <div box-="square" class="column">
        <p>Default</p>
        <div is-="separator"></div>
        <p>Separator</p>
    </div>
    <div box-="square" class="column">
        <p>Bisecting</p>
        <div is-="separator" cap-="bisect"></div>
        <p>Separator</p>
    </div>
</div>
<div class="column">
    <div box-="square" class="row">
        <p>Default</p>
        <div is-="separator" direction-="y"></div>
        <p>Separator</p>
    </div>
    <div box-="square" class="row">
        <p>Bisecting</p>
        <div is-="separator" direction-="y" cap-="bisect"></div>
        <p>Separator</p>
    </div>
</div>
`}
/>

#### Edge Caps

`cap-="edge"` clips off the edges of the separator by `0.5ch` making it ideal for corners

<Example
    stylesheets={[separatorStyle]}
    css={`
        body {
            display: flex;
            flex-direction: column;
            gap: 1lh;
        }
        .column {
            display: flex;
            flex-direction: column;
        }
        div[direction-='y'] {
            height: 2lh;
        }
    `}
    html={`
<div class="column">
    <span>bisect</span>
    <div is-="separator" cap-="bisect" direction-="y"></div>
    <div is-="separator" cap-="edge"></div>
    <span>edge</span>
</div>
<div class="column">
    <span>bisect</span>
    <div is-="separator" cap-="bisect" direction-="y"></div>
    <div is-="separator"></div>
    <span>default</span>
</div>
<div class="column">
    <span>bisect</span>
    <div is-="separator" cap-="bisect" direction-="y"></div>
    <div is-="separator" cap-="bisect"></div>
    <span>bisect</span>
</div>
`}
/>

#### Start and End Caps

You can specify two values for the `cap-` attribute to control the start and end of the separator

```html
<div is-="separator" cap-="edge bisect"></div>
<div is-="separator" cap-="default edge"></div>
<div is-="separator" cap-="bisect default"></div>
```

<Example
    stylesheets={[separatorStyle, boxStyle]}
    css={`
        body {
            display: flex;
            flex-direction: column;
            gap: 1lh;
        }
        .column {
            display: flex;
            flex-direction: column;
        }
        div[direction-='y'] {
            height: 2lh;
        }
    `}
    html={`
<div box-="square" class="column">
    <div class="column">
        <span>edge bisect</span>
        <div is-="separator" cap-="edge bisect"></div>
    </div>
    <div class="column">
        <span>default edge</span>
        <div is-="separator" cap-="default edge"></div>
    </div>
    <div class="column">
        <span>bisect default</span>
        <div is-="separator" cap-="bisect default"></div>
    </div>
</div>
`}
/>

## Reference

### Properties

Use the following custom CSS properties to style separators

- `--separator-width`: The width of the separator line
- `--separator-color`: The color of the separator line
- `--separator-background`: The background color of the separator behind the line

<Example
    stylesheets={[separatorStyle]}
    css={`
        body {
            display: flex;
            flex-direction: column;
        }
        div[is-='separator'] {
            --separator-width: 1px;
            --separator-color: orange;
            --separator-background: #444;
        }
    `}
    html={`<p>The quick green dog</p>
<div is-="separator"></div>
<p>eats the lazy fox</p>`}
/>

### Extending

To extend the Separator stylesheet, define a CSS rule on the `components` layer

```css
@layer components {
    input[type='checkbox'] {
        /* ... */
    }
}
```

### Scope

- All elements with the `is-~="separator"` selector

```css
input[type='checkbox'] {
    /* ... */
}
```