Separator

A simple visual divider for separating sections of content. Supports horizontal and vertical orientation, an optional centered label, and semantic vs. decorative modes.

Features

• ↔️ Horizontal (default) and ↕️ Vertical orientations
• 🏷️ Optional label — centered text on the divider line
• 🎨 6 Theme Colors: primary, secondary, info, success, warning, error
• ♿ Accessible: decorative mode sets aria-hidden; semantic mode uses role="separator"
• 🔧 Customizable line thickness, color, and spacing via CSS custom properties

Source Code

View Source Code

import { define, prop, html } from '@vielzeug/craftit';

import type { ThemeColor } from '../../types';

import { colorThemeMixin } from '../../styles';
import componentStyles from './separator.css?inline';

/** Separator component properties */
export type BitSeparatorProps = {
  /** Theme color tint */
  color?: ThemeColor;
  /** Decorative only (default true) — set to false for semantic separators */
  decorative?: boolean;
  /** Optional label text centered on the separator */
  label?: string;
  /** Orientation of the separator */
  orientation?: 'horizontal' | 'vertical';
};

/**
 * A simple visual divider between sections of content.
 *
 * @element bit-separator
 *
 * @attr {string} orientation - 'horizontal' (default) | 'vertical'
 * @attr {boolean} decorative - When true (default), aria-hidden is applied
 * @attr {string} label - Optional centered label text
 * @attr {string} color - Theme color
 *
 * @cssprop --separator-color - Line color
 * @cssprop --separator-size - Line thickness
 * @cssprop --separator-spacing - Vertical margin
 *
 * @part wrapper - Root wrapper container.
 * @part separator - Separator element.
 * @part label - Label element.
 * @example
 * ```html
 * <bit-separator></bit-separator>
 * <bit-separator label="or"></bit-separator>
 * <bit-separator orientation="vertical"></bit-separator>
 * ```
 */
export const SEPARATOR_TAG = define<BitSeparatorProps>('bit-separator', {
  props: {
    color: undefined,
    decorative: prop.bool(true),
    label: undefined,
    orientation: prop.oneOf(['horizontal', 'vertical'] as const, 'horizontal'),
  },
  setup(props) {
    const roleAttr = () => (props.decorative.value ? 'none' : 'separator');
    const ariaHidden = () => (props.decorative.value ? 'true' : null);

    return () => html`
      ${() =>
        props.label.value
          ? html`
              <div class="separator-wrapper" part="wrapper">
                <hr
                  class="separator"
                  part="separator"
                  :role="${roleAttr}"
                  :aria-hidden="${ariaHidden}"
                  :aria-orientation="${() => props.orientation.value}" />
                <span class="separator-label" part="label">${() => props.label.value}</span>
                <hr class="separator" part="separator" :role="${roleAttr}" :aria-hidden="${ariaHidden}" />
              </div>
            `
          : html`
              <hr
                class="separator"
                part="separator"
                :role="${roleAttr}"
                :aria-hidden="${ariaHidden}"
                :aria-orientation="${() => props.orientation.value}" />
            `}
    `;
  },
  styles: [colorThemeMixin, componentStyles],
});

Basic Usage

<p>Section one content.</p>
<bit-separator></bit-separator>
<p>Section two content.</p>

<script type="module">
  import '@vielzeug/buildit';
</script>

Horizontal (Default)

PreviewCode

RTL

Vertical

Set orientation="vertical" for inline use. The separator stretches to match the line height of surrounding flex / inline content.

PreviewCode

RTL

With Label

Add a centered label to split the line into two segments.

PreviewCode

RTL

Colors

PreviewCode

RTL

Colors with Label

PreviewCode

RTL

Semantic Separator

By default the separator is decorative (aria-hidden="true"). Set decorative="false" for sections where the separator carries structural meaning.

<bit-separator decorative="false" aria-label="End of navigation"></bit-separator>

API Reference

Attributes

Attribute	Type	Default	Description
orientation	'horizontal' | 'vertical'	'horizontal'	Direction of the divider line
decorative	boolean	true	When true, sets aria-hidden. Set to false for semantic separators
label	string	—	Optional text centered on the separator line
color	'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error'	—	Theme color for the line

CSS Custom Properties

Property	Description
--separator-color	Line color
--separator-size	Line thickness (defaults to 1px)
--separator-spacing	Vertical margin above and below the line

Accessibility

The separator component follows WAI-ARIA best practices.

bit-separator

✅ Screen Readers

• By default, the separator is decorative and has aria-hidden="true".
• Set decorative="false" for separators that carry structural meaning and pair with aria-label to describe the separation.