Anchor
Impulse::AnchorComponent renders an <awc-anchor> element: a floating element, such as a tooltip or a menu, that positions itself next to an anchor (another element on the page) and stays inside the viewport as the page scrolls or resizes. It is configured entirely with attributes, so it needs no JavaScript of your own.
The anchor is often the trigger (the element that is clicked or hovered to show the floating element), but it doesn't have to be. For example, a menu opened by a chevron button can be anchored to the whole field.
Anchor or useFloatingUI?
Use Impulse::AnchorComponent when you are writing markup and want something positioned. If you are writing your own impulse element that opens and closes a floating element, use the useFloatingUI hook instead. Both share the same positioning logic and defaults.
Usage
<button type="button" id="anchor-button" class="btn btn-primary">Anchor</button>
<%= render(Impulse::AnchorComponent.new(anchor_id: "anchor-button", active: true, class: "popover bs-popover-auto")) do %>
<div class="popover-body">I am anchored to the button!</div>
<% end %>Arguments
Keyword arguments
| Name | Default | Description |
|---|---|---|
| anchor_id | N/A | The id of the element to position against. |
| active | false | Whether the element is positioned when the page loads. Call start and stop to change it from JavaScript. While false, the element stays where it was last placed, which before it first starts is the viewport's top-left corner. |
| placement | "bottom" | The preferred placement. The actual placement may vary to keep the element inside the viewport. One of "top", "top-start", "top-end", "right", "right-start", "right-end", "bottom", "bottom-start", "bottom-end", "left", "left-start", or "left-end". |
| strategy | "fixed" | The value of the position CSS property. One of "absolute" or "fixed". |
| distance | 0 | The distance in pixels away from the anchor. |
| skidding | 0 | The distance in pixels along the anchor. |
| sync | nil | Matches the element's size to the anchor's. One of "height", "width", or "both". |
| flip | true | Flips the element to another placement when the preferred one doesn't fit. |
| flip_padding | 0 | The padding in pixels to keep from the viewport edge before flipping. Raised past auto_size_padding on the auto sized axis while auto_size is set. |
| fallback_placements | [] | The placements to try, in order, when the preferred one doesn't fit. By default, the opposite side is tried. |
| fallback_strategy | "bestFit" | What to do when no placement fits. "bestFit" uses the placement that fits best, and "initialPlacement" uses placement, or the side keep_flipped keeps. |
| keep_flipped | false | Keeps the side the element flipped to until it's deactivated, instead of trying placement first on every reposition, so it doesn't jump back once its content shrinks. It still flips again when that side stops fitting. |
| shift | true | Shifts the element along the anchor to keep it inside the viewport. |
| shift_padding | 0 | The padding in pixels to keep from the viewport edge while shifting. |
| auto_size | nil | Exposes the space available to the element as the --awc-auto-size-height and --awc-auto-size-width CSS custom properties. One of "height", "width", or "both". |
| auto_size_padding | 0 | The padding in pixels to keep from the viewport edge when measuring the available space. |
| arrow_padding | 0 | The padding in pixels between the arrow and the edges of the element. |
Any other keyword arguments are passed to the <awc-anchor> element as HTML attributes.
Examples
Adding an arrow
Mark a child element with data-arrow to have it point at the anchor. The element's chosen placement is set as its x-placement attribute, which you can use to style the arrow for each side.
<%= render(Impulse::AnchorComponent.new(anchor_id: "anchor-button", active: true, distance: 8)) do %>
<div class="arrow" data-arrow></div>
<div class="popover-body">I am anchored to the button!</div>
<% end %>Fitting the viewport
Set auto_size and cap the element's size with the custom property it exposes, so a tall menu scrolls instead of overflowing the viewport. When the cap squashes the element and the other side of the anchor has more room, the element flips there.
<%= render(Impulse::AnchorComponent.new(anchor_id: "anchor-button", active: true, auto_size: "height", auto_size_padding: 8, class: "menu")) do %>
...
<% end %>.menu {
max-height: var(--awc-auto-size-height);
overflow-y: auto;
}Imports
import '@ambiki/impulse-view-components/anchor';The component has no styles of its own.