Divider

Overview

Divider separates content sections with a consistent, token-based border. It is a layout primitive that creates clear visual separation between related sections, groups, forms, menus, toolbars, and inline items. Divider can be horizontal or vertical, and optionally include a label for context. It uses the border-border token to stay theme-aware across light, dark, and branded themes.

Why this exists

Without a shared Divider pattern, every page uses inconsistent border colors, spacing, and line thickness — border-gray-200 here, a .5px line there, my-8 on one page and my-4 on another. Divider standardises separation: subtle, token-based, theme-aware, and consistent across every page and product screen — whether a dashboard, settings panel, auth form, or ERP back office.

Mental model

• Spacing creates breathing room between elements.
• Divider creates visual separation — a deliberate boundary.
• Use Divider when two content groups need a clearer boundary than spacing alone provides.
• Use it sparingly so the interface does not become noisy. Too many dividers compete for attention and make layouts feel busy.
• Divider is not a layout tool — it is a visual cue. Page structure belongs to Stack, Grid, and Container.

When to use

• Separating form sections — personal info, address, payment in a checkout or settings form
• Separating settings groups — account settings, notification preferences, privacy controls
• Separating card sections — card header from body, body from footer, or distinct content blocks inside a card
• Separating menu groups — file operations, edit actions, view options in a dropdown or context menu
• Separating page sections — hero, features, pricing, FAQ on a marketing page
• Labelled auth dividers — "Or continue with" between email login and social auth buttons
• Vertical dividers between toolbar or navigation items — separating nav links, breadcrumb segments, or inline action buttons
• Dashboard and admin metadata groups — separating stats, charts, and data table sections

When not to use

• Do not use Divider to fix poor spacing — if content looks cramped, increase padding or margin first
• Do not use Divider between every small element — dense lists, table rows, and stacked badges do not need dividers
• Do not use Divider inside buttons, badges, table cells, or compact form controls — these elements are too small for meaningful separation
• Do not use vertical Divider when spacing or grouping is enough — a gap-4 between toolbar items may suffice without a vertical line
• Do not use labelled Divider when the label does not add meaning — a divider says "separator" without text; adding a label should clarify what is being separated

Basic example

A horizontal divider separates two content sections inside a card. The line uses the border-border token and adapts to dark mode automatically:

<div class="rounded-xl border border-border bg-card p-6 space-y-6">
  <div>
    <h3 class="font-semibold text-foreground mb-2">Account settings</h3>
    <p class="text-sm text-muted-foreground">Manage your email, password, and profile information.</p>
  </div>
  <hr class="border-border" />
  <div>
    <h3 class="font-semibold text-foreground mb-2">Notifications</h3>
    <p class="text-sm text-muted-foreground">Configure which updates you receive.</p>
  </div>
</div>

Common patterns

<!-- Labelled divider -->
<div class="relative">
  <div class="absolute inset-0 flex items-center" aria-hidden="true">
    <div class="w-full border-t border-border"></div>
  </div>
  <div class="relative flex justify-center">
    <span class="bg-background px-3 text-sm text-muted-foreground">Or continue with</span>
  </div>
</div>

<!-- Vertical divider between inline items -->
<div class="flex items-center h-10 gap-4 text-sm text-muted-foreground">
  <span>Dashboard</span>
  <div class="w-px h-full bg-border" aria-hidden="true"></div>
  <span>Analytics</span>
  <div class="w-px h-full bg-border" aria-hidden="true"></div>
  <span>Settings</span>
</div>

Variants

Divider has no semantic variants. Its common visual patterns are:

• Horizontal — a full-width line separating stacked content sections, created with <hr class="border-border" />
• Labelled — a horizontal line with centered text, commonly used in auth forms ("Or continue with") or section group labels
• Vertical — a short vertical line between inline items in a toolbar, nav, or breadcrumb, created with <div class="w-px h-full bg-border" aria-hidden="true"></div>

Sizes / spacing

Divider uses the default border width from the border-border token (1 px). Surrounding spacing is controlled with standard Tailwind spacing utilities. Use my-4 for tight groups, my-6 for standard card sections, and my-8 or my-10 for major page section breaks.

States

Divider itself has no interaction states. It should not be hoverable, focusable, selected, loading, disabled, or clickable. Only surrounding content or interactive children may have their own states.

Anatomy

• Line element — a <hr> for horizontal dividers, or a <div> with border-t or bg-border for custom styles
• Border token — border-border for theme-aware color
• Optional label — centered text inside a labelled divider, styled with text-muted-foreground
• Optional vertical orientation — a w-px h-full bg-border element for inline separation
• Surrounding spacing — my-* or space-y-* for breathing room around the line
• Decorative vs semantic — decorative lines use aria-hidden="true"; semantic separators use <hr> (native role="separator")

Usage guidelines

• Use subtle token-based borders — border-border is the correct token
• Pair dividers with adequate spacing — a divider without my-* feels cramped
• Keep labelled dividers short — "Or continue with", "Account info", "Payment method"
• Avoid overusing lines — too many dividers create visual noise; prefer spacing first
• Use vertical dividers only in compact inline groups — toolbars, breadcrumbs, nav links
• Keep divider color theme-aware — always use border-border or bg-border, never raw gray colors

Do and Don't

Accessibility

Divider can be decorative or semantic depending on context:

• Decorative visual lines — use aria-hidden="true" if the divider element is rendered purely for visual separation and carries no meaning
• Semantic separators — use <hr> which has native role="separator". Use a <div> with explicit role="separator" when the line cannot be an <hr> (e.g. labelled dividers)
• Do not add ARIA roles only for styling — a plain <hr> is sufficient as a visual rule. Only add semantics when the separation conveys meaning
• Vertical separators — set aria-orientation="vertical" only when using role="separator" on a vertical element. Pure decorative vertical lines should use aria-hidden="true"
• Labelled dividers — include readable text with sufficient contrast. The label itself does not require a specific role; it is a visual annotation

Customization

Divider should use Byteion border tokens, spacing tokens, and semantic utilities:

• Line color — border-border for horizontal <hr>, bg-border for vertical or custom line elements
• Label text — text-muted-foreground for the centred label in labelled dividers
• Label background — bg-background or bg-card to match the parent surface so the label appears to sit on top of the line
• Spacing — my-* or space-y-* for consistent gaps
• Avoid — hardcoded gray colors, arbitrary heights or thicknesses, and non-token spacing values

HTML example

<!-- Horizontal divider -->
<hr class="border-border my-6" />

<!-- Horizontal divider via border-top on a wrapper -->
<div class="border-t border-border pt-6 mt-6">
  <h3 class="font-semibold text-foreground">Notifications</h3>
</div>

<!-- Labelled divider -->
<div class="relative my-6">
  <div class="absolute inset-0 flex items-center" aria-hidden="true">
    <div class="w-full border-t border-border"></div>
  </div>
  <div class="relative flex justify-center">
    <span class="bg-background px-3 text-sm text-muted-foreground">Or continue with</span>
  </div>
</div>

<!-- Vertical divider -->
<div class="flex items-center h-8 gap-3 text-sm text-muted-foreground">
  <a href="#" class="hover:text-foreground">Dashboard</a>
  <div class="w-px h-full bg-border" aria-hidden="true"></div>
  <a href="#" class="hover:text-foreground">Reports</a>
  <div class="w-px h-full bg-border" aria-hidden="true"></div>
  <a href="#" class="hover:text-foreground">Settings</a>
</div>

React example

React uses the same HTML structure and utility classes. There is no Divider component in @byteion/react — use plain <hr> with token classes:

function SettingsForm() {
  return (
    <div className="space-y-6">
      <div>
        <h2 className="font-semibold text-foreground">Profile</h2>
        <!-- form fields -->
      </div>
      <hr className="border-border" />
      <div>
        <h2 className="font-semibold text-foreground">Preferences</h2>
        <!-- form fields -->
      </div>
    </div>
  );
}

function AuthDivider() {
  return (
    <div className="relative my-6">
      <div className="absolute inset-0 flex items-center" aria-hidden="true">
        <div className="w-full border-t border-border" />
      </div>
      <div className="relative flex justify-center">
        <span className="bg-background px-3 text-sm text-muted-foreground">
          Or continue with
        </span>
      </div>
    </div>
  );
}

function NavCluster() {
  return (
    <div className="flex items-center h-8 gap-3 text-sm text-muted-foreground">
      <a href="#" className="hover:text-foreground">Dashboard</a>
      <div className="w-px h-full bg-border" aria-hidden="true" />
      <a href="#" className="hover:text-foreground">Reports</a>
      <div className="w-px h-full bg-border" aria-hidden="true" />
      <a href="#" className="hover:text-foreground">Settings</a>
    </div>
  );
}

Vue example

Vue uses the same HTML structure and utility classes. There is no Divider component in @byteion/vue:

<template>
  <div class="space-y-6">
    <div>
      <h2 class="font-semibold text-foreground">Profile</h2>
      <!-- form fields -->
    </div>
    <hr class="border-border" />
    <div>
      <h2 class="font-semibold text-foreground">Preferences</h2>
      <!-- form fields -->
    </div>
  </div>

  <!-- Labelled divider -->
  <div class="relative my-6">
    <div class="absolute inset-0 flex items-center" aria-hidden="true">
      <div class="w-full border-t border-border"></div>
    </div>
    <div class="relative flex justify-center">
      <span class="bg-background px-3 text-sm text-muted-foreground">
        Or continue with
      </span>
    </div>
  </div>

  <!-- Vertical divider -->
  <div class="flex items-center h-8 gap-3 text-sm text-muted-foreground">
    <a href="#" class="hover:text-foreground">Dashboard</a>
    <div class="w-px h-full bg-border" aria-hidden="true"></div>
    <a href="#" class="hover:text-foreground">Reports</a>
    <div class="w-px h-full bg-border" aria-hidden="true"></div>
    <a href="#" class="hover:text-foreground">Settings</a>
  </div>
</template>

API Reference

Divider is a pure HTML/Tailwind pattern — it has no React component, no Vue component, and no JavaScript API. The pattern is applied by adding Tailwind utility classes to a semantic <hr> or a decorative <div>. No custom props or data attributes are required.

Developer tips

• Use Divider inside Card, Settings, Menu, Form, Auth, Toolbar, and Page sections — these are the most common contexts where visual separation is needed
• Test dark mode after changing border tokens — border-border adapts automatically, but any custom border color must be tested in both modes
• Keep labelled dividers short — one to four words is ideal. Long labels defeat the purpose of a quick scannable separator
• Prefer spacing first, divider second — if my-8 provides enough visual separation, skip the divider
• Do not rely on Divider to create page layout — page structure belongs to Stack, Grid, and Container

Common mistakes

• Using Divider between every row — dense lists, table rows, and stacked form fields do not need dividers between each item
• Using raw neutral colors — border-gray-200 breaks in dark mode. Always use border-border
• Using Divider where spacing is enough — if my-8 creates sufficient separation, adding a line is redundant
• Making decorative dividers semantic — a purely visual line does not need role="separator". Use aria-hidden="true" instead
• Forgetting aria-orientation for semantic vertical separators — if a vertical element has role="separator", it must specify aria-orientation="vertical"
• Putting interactive content inside a labelled divider — buttons, links, and inputs should not be embedded inside a separator

Production usage tips

• Test dark mode and branded themes — border-border adapts automatically, but verify the divider remains subtle and visible in all themes
• Verify label contrast — labelled dividers use text-muted-foreground; verify the text meets WCAG contrast against the parent background
• Keep horizontal spacing consistent across page sections — use the same my-* value for dividers at the same hierarchy level
• Keep React / Vue output visually aligned with HTML — the canonical <hr class="border-border" /> pattern is the source of truth across all frameworks
• Avoid decorative line overload in data-heavy dashboards — dashboards with charts, tables, and stats should minimise dividers to reduce cognitive load

Premium examples

Pro patterns available in Byteion Pro:

• Settings page section dividers — labelled dividers separating account, notifications, billing, and team preference groups in a settings layout
• ERP form group separators — horizontal dividers with section titles inside complex ERP order or invoice forms
• Ecommerce admin section breaks — dividers between order summary, shipping details, payment info, and customer notes in an admin panel
• Auth page "Continue with" divider — a clean labelled divider between email login and social auth provider buttons
• Dashboard toolbar vertical divider — compact vertical dividers between toolbar action groups (filter, export, refresh, fullscreen)
• POS checkout summary separators — horizontal dividers separating itemised totals, tax, discount, and grand total in a POS checkout panel

Related components

• Stack — vertical spacing between sections, often used with Divider between stacked blocks
• Cluster — horizontal inline grouping where vertical dividers may appear between items
• Container — page-level width for divider-contained sections
• Card — surface container where dividers separate header, body, and footer
• Section — page section primitive that can be spaced or separated with dividers

API Reference

Related components

Pair this component with adjacent Byteion primitives from the same workflow: form controls for data entry, feedback components for validation, and layout primitives for spacing.

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

Remote / AJAX