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 { defineComponent, html, typed } 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
 *
 * @example
 * ```html
 * <bit-separator></bit-separator>
 * <bit-separator label="or"></bit-separator>
 * <bit-separator orientation="vertical"></bit-separator>
 * ```
 */
export const SEPARATOR_TAG = defineComponent<BitSeparatorProps>({
  props: {
    color: typed<BitSeparatorProps['color']>(undefined),
    decorative: typed<boolean>(true),
    label: typed<string | undefined>(undefined),
    orientation: typed<BitSeparatorProps['orientation']>('horizontal'),
  },
  setup({ props }) {
    return html`
      ${() =>
        props.label.value
          ? html`
              <div class="separator-wrapper" part="wrapper">
                <hr
                  class="separator"
                  part="separator"
                  :role="${() => (props.decorative.value ? 'none' : 'separator')}"
                  :aria-hidden="${() => (props.decorative.value ? 'true' : null)}"
                  :aria-orientation="${() => props.orientation.value}" />
                <span class="separator-label" part="label">${() => props.label.value}</span>
                <hr
                  class="separator"
                  part="separator"
                  :role="${() => (props.decorative.value ? 'none' : 'separator')}"
                  :aria-hidden="${() => (props.decorative.value ? 'true' : null)}" />
              </div>
            `
          : html`
              <hr
                class="separator"
                part="separator"
                :role="${() => (props.decorative.value ? 'none' : 'separator')}"
                :aria-hidden="${() => (props.decorative.value ? 'true' : null)}"
                :aria-orientation="${() => props.orientation.value}" />
            `}
    `;
  },
  styles: [colorThemeMixin, componentStyles],
  tag: 'bit-separator',
});

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.