;
};
A divider creates a visual break between related pieces of content. Use it to clarify grouping without adding another heading, card, or container.
## 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 and `title-alignment="start"` doubles as a lightweight section label. Use this pattern when a heading (`
`, `
`) 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
Use horizontal dividers to separate stacked content, sections, list rows, or blocks inside a page.
Use vertical dividers between side-by-side controls or columns when spacing alone does not show the relationship clearly.
### Placement
For a clearer representation of elements dependent on specific categories or criteria, the divider plays a crucial role in delineating sections.
Use dividers in dense lists when repeated items need stronger row boundaries for scanning.
### 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.
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDivider } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDivider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDivider],
template: `
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Vertical
Set `orientation="vertical"` when the divider separates side-by-side content, such as adjacent actions or columns.
.divider--vertical-example {
display: flex;
align-items: center;
justify-content: center;
block-size: 120px;
gap: var(--bq-spacing-m);
}
```
When using a vertical divider, ensure the container has enough height for the stroke to render and sufficient horizontal padding so the line does not feel cramped.
## Options
### Dashed
Use `dashed` 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.
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDivider } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDivider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDivider],
template: `
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Title alignment
Use `title-alignment` to place title content at the start, middle, or end of the divider.
bq-divider {
white-space: nowrap;
}
Text start
Text middle
Text end
`}
>
```css styles.css icon="css" theme={"theme":{"light":"one-light","dark":"night-owl"}}
bq-divider {
white-space: nowrap;
}
```
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
Text startText middleText end
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDivider } from "@beeq/react";
import "./styles.css";
Text startText middleText end
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDivider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDivider],
template: `
Text startText middleText end
`,
styles: [`
bq-divider {
white-space: nowrap;
}
`],
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Text startText middleText end
```
### Stroke
Use stroke attributes to match the divider to a specific visual treatment. Set `stroke-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.
Section
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Section
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDivider } from "@beeq/react";
Section
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDivider } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDivider],
template: `
Section
`,
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
Section
```
## Best practices
Do
Use dividers to clarify groups that already belong together.
Don't
Do not use dividers to force unrelated content into the same section.
Do
Prefer spacing first, then add a divider when the boundary still needs emphasis.
Don't
Do not add repeated dividers that make the layout feel busy.
Do
Use title content only when the label helps users understand the next group.
Don't
Do not use divider title content as a replacement for a real heading.
Do
Keep stroke color and thickness consistent with the surrounding hierarchy.
Don't
Do 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)` |
Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties).
## Resources
Explore divider variants and states in Storybook
View the component source on GitHub
A divider creates a visual break between related pieces of content. Use it to clarify grouping without adding another heading, card, or container.
## When to use
| Part | Element | Description |
| ----- | ------- | ------------------------------------------------ |
| **1** | Stroke | The visual line that separates content |
| **2** | Text | Optional text content placed in the default slot |
## Design guidelines
### Orientation