When to use
Use dividers when
- Content groups need a subtle visual boundary
- A list or page section needs clearer scanning
- Related items sit close together and spacing alone is not enough
- Horizontal or vertical separation improves the layout hierarchy
Do not use dividers when
- Whitespace already separates the content clearly
- The divider adds clutter without improving comprehension
- A heading, card, or layout change would explain the grouping better
- Users need a semantic landmark or navigational structure
Patterns
Full-bleed and inset
A full-bleed divider runs edge-to-edge across its container. This is the default (stroke-basis="0") and suits top-level page and card section breaks where content is not indented.
An inset divider sets stroke-basis to the pixel offset of the content below it — typically the width of a list item’s leading avatar or icon. The stroke starts at that offset rather than the container edge, keeping it visually aligned with the text column. Use this pattern in rich lists and inbox-style data rows.
List rows
Place a divider between repeated items in dense views — inboxes, contact lists, or data tables — when row boundaries would otherwise blur together and impair scanning.Title separation
A divider with slot content andtitle-alignment="start" doubles as a lightweight section label. Use this pattern when a heading (<h2>, <h3>) would add too much visual weight but the group still needs a short name.
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Stroke | The visual line that separates content |
| 2 | Text | Optional text content placed in the default slot |
Design guidelines
Orientation
Placement
Sizing
Divider strokes default to a thin line. Increase
stroke-thickness only when the divider must match a stronger visual treatment in the surrounding layout.Usage
Default
The simplest use — no attributes or slot content required. The divider renders as a full-width horizontal line.Vertical
Setorientation="vertical" when the divider separates side-by-side content, such as adjacent actions or columns.
Options
Dashed
Usedashed for a lighter visual boundary. Adjust stroke-dash-width, stroke-dash-gap, and stroke-linecap when the dash pattern needs to match the surrounding interface.
Title alignment
Usetitle-alignment to place title content at the start, middle, or end of the divider.
Stroke
Use stroke attributes to match the divider to a specific visual treatment. Setstroke-basis to create an inset divider — give it the pixel width of the leading icon or avatar in your list so the line starts at the text column rather than the container edge.
Best practices
DoUse dividers to clarify groups that already belong together.
Don’tDo not use dividers to force unrelated content into the same section.
DoPrefer spacing first, then add a divider when the boundary still needs emphasis.
Don’tDo not add repeated dividers that make the layout feel busy.
DoUse title content only when the label helps users understand the next group.
Don’tDo not use divider title content as a replacement for a real heading.
DoKeep stroke color and thickness consistent with the surrounding hierarchy.
Don’tDo not rely on color or line style as the only way to communicate meaning.
Accessibility
- Divider strokes are rendered as SVG lines with
aria-hidden="true", so assistive technologies ignore the decorative line. - Content passed into the default slot remains available to assistive technologies.
- Use slot content only for short labels that help identify the following group.
- Do not rely on a divider alone to communicate page structure. Use headings, landmarks, or list semantics when users need navigation or hierarchy.
- Keep vertical dividers out of the keyboard focus order unless nearby interactive content already provides a clear path.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
dashed | dashed | If true, the divider uses a dashed pattern | boolean | false |
orientation | orientation | The divider orientation | 'horizontal' | 'vertical' | 'horizontal' |
strokeBasis | stroke-basis | Minimum pixel offset before the stroke starts; set to the width of a leading icon or avatar to create an inset divider | number | 0 |
strokeColor | stroke-color | Stroke color token from the palette | string | 'stroke--primary' |
strokeDashGap | stroke-dash-gap | Gap between dashes when dashed is set | number | 7 |
strokeDashWidth | stroke-dash-width | Width of each dash when dashed is set | number | 12 |
strokeLinecap | stroke-linecap | Line cap style when dashed is set | 'butt' | 'round' | 'square' | 'butt' |
strokeThickness | stroke-thickness | Stroke thickness, in pixels | number | 1 |
titleAlignment | title-alignment | Alignment of title content on the divider axis | 'end' | 'middle' | 'start' | 'middle' |
Slots
| Slot | Description |
|---|---|
| (default) | Optional title content displayed between divider strokes |
Shadow parts
| Part | Description |
|---|---|
base | The component’s internal wrapper |
dash-end | The internal SVG wrapper for the end stroke |
dash-end-line | The line element for the end stroke |
dash-start | The internal SVG wrapper for the start stroke |
dash-start-line | The line element for the start stroke |
CSS custom properties
| Variable | Description | Default |
|---|---|---|
--bq-divider--color | Divider color | var(--bq-stroke--primary) |
--bq-divider--title-marginX | Space between title content and delimiter strokes | var(--bq-spacing-m) |
Resources
Interactive playground
Explore divider variants and states in Storybook
Source code
View the component source on GitHub