Placement
The placement field on each step controls where the tooltip appears relative to its target element. Borda uses a 3×3 grid system with 9 named positions.
Values
| Placement | Position |
|---|---|
TOP_START | Above the target, aligned to its left edge |
TOP_CENTER | Above the target, centered |
TOP_END | Above the target, aligned to its right edge |
MIDDLE_START | Left of the target, vertically centered |
MIDDLE_CENTER | Centered on the target |
MIDDLE_END | Right of the target, vertically centered |
BOTTOM_START | Below the target, aligned to its left edge |
BOTTOM_CENTER | Below the target, centered |
BOTTOM_END | Below the target, aligned to its right edge |
import { ComponentPlacement } from '@retoo/borda';
await borda.mount({
steps: [
{
target: '#sidebar',
title: 'Navigation',
description: 'Browse sections here.',
placement: ComponentPlacement.MIDDLE_END,
},
{
target: '#header',
title: 'Header',
description: 'Sits below the target, aligned left.',
placement: ComponentPlacement.BOTTOM_START,
},
{
target: '#hero-banner',
title: 'Hero',
description: 'Centered directly on top of the target.',
placement: ComponentPlacement.MIDDLE_CENTER,
},
],
});
Auto-placement
When the requested placement doesn't fit in the viewport, Borda can automatically flip the tooltip to a fallback position. This is enabled by default. The default fallback chain tries the mirrored side first, then centered variants, then the opposite-alignment sides, and finally the perpendicular (middle-*) sides.
Configure the fallback chain through the tooltip's autoPlacement option:
await borda.mount({
steps: [
{
target: '#element',
title: 'Title',
description: 'Description',
placement: ComponentPlacement.TOP_CENTER,
},
],
tourTooltip: {
autoPlacement: {
fallback: [
ComponentPlacement.BOTTOM_CENTER,
ComponentPlacement.MIDDLE_END,
],
},
},
});
The first placement from the fallback list that fits in the viewport wins. If none fit, Borda falls back to whichever candidate overflows the least, then shifts it to stay attached to the target without ever overlapping it.
Disable auto-placement to use the requested position as-is:
tourTooltip: {
autoPlacement: false,
}