Anchored region

Anchored regions are containers that position content relative to the anchor element.

The anchored region can react to the available space between the anchor and a parent viewport element. Depending on the attributes set, the region can be placed on the side of the anchor with the most available space, or it can resize itself based on that space.

Use cases:

• creating a component that is visible relative to another component (for information, this component is used to implement the Tooltip component)
• creating a layout that reacts to layout changes
• creating a layout where elements are not viewed in DOM order (1)

warning

(1) Elements that are not viewed in the same order as the DOM order could cause accessibility issues with screen readers.

Example

Content after button in DOM

info

The live example includes css styling to ensure the components fit into the example container.

Genesis

Declaration

<rapid-anchored-region></rapid-anchored-region>

Usage

@customElement({
  name: 'my-element',
  template: html`
    <div id="viewport">
      <button id="anchor">
        Button is an anchor, defined first in the DOM
      </button>
      <rapid-anchored-region
        anchor="anchor"
        vertical-positioning-mode="locktodefault"
        vertical-default-position="top">
        This shows up above the button, even though it's after it in the DOM
      </rapid-anchored-region>
    </div>
  `,
})
export class MyElement extends GenesisElement { }

React

Declaration

<rapid-anchored-region></rapid-anchored-region>

Usage

export function MyComponent() {
  return (
    <div id="viewport">
      <button id="anchor">
        Button is an anchor, defined first in the DOM
      </button>
      <rapid-anchored-region
        anchor="anchor"
        vertical-positioning-mode="locktodefault"
        vertical-default-position="top">
        This shows up above the button, even though it's after it in the DOM
      </rapid-anchored-region>
    </div>
  );
}

Angular

Declaration

<rapid-anchored-region></rapid-anchored-region>

Usage

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { FormsModule } from '@angular/forms';
@Component({
  selector: 'my-root',
  template: `
    <div id="viewport">
      <button id="anchor">
        Button is an anchor, defined first in the DOM
      </button>
      <rapid-anchored-region
        anchor="anchor"
        vertical-positioning-mode="locktodefault"
        vertical-default-position="top">
        This shows up above the button, even though it's after it in the DOM
      </rapid-anchored-region>
    </div>
  `,
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  imports: [FormsModule],
})
export class AppComponent { }

API

Attributes

Attribute	Type	Description	Example
anchor	string	The HTML ID of the anchor element this region is positioned relative to.	<rapid-anchored-layout anchor="header-id">
viewport	string	The HTML ID of the viewport element this region is positioned relative to.	<rapid-anchored-layout viewport="main-content">
horizontal-positioning-mode	"uncontrolled" | "locktodefault" | "dynamic"	Controls horizontal placement. Default: "uncontrolled". locktodefault forces the default position, dynamic decides placement based on available space, and uncontrolled does not control placement on the horizontal axis	<rapid-anchored-layout horizontal-positioning-mode="dynamic">
horizontal-default-position	"start" | "end" | "left" | "right" | "center" | "unset"	Default horizontal position relative to anchor. Default: "unset"	<rapid-anchored-layout horizontal-default-position="center">
horizontal-viewport-lock	boolean	Controls whether the anchored region always remains fully in the viewport on the horizontal axis. If true, the position is adjusted to stay within viewport bounds, detaching from the anchor if necessary. This prevents overflow and clipping. Default: false	<rapid-anchored-layout horizontal-viewport-lock>
horizontal-inset	boolean	Controls whether the region can overlap the anchor on the horizontal axis. Default: false	<rapid-anchored-layout horizontal-inset>
horizontal-threshold	number	Sets how narrow the space allocated to the default position has to be before the widest area is selected for the layout.	<rapid-anchored-layout horizontal-threshold="10">
horizontal-scaling	"anchor" | "fill" | "content"	How width is calculated. Default: "content"	<rapid-anchored-layout horizontal-scaling="content">
vertical-positioning-mode	"uncontrolled" | "locktodefault" | "dynamic"	Sets logic for vertical placement. Default: "uncontrolled". locktodefault forces the default position, dynamic decides placement based on available space, and uncontrolled does not control placement on the horizontal axis	<rapid-anchored-layout vertical-positioning-mode="dynamic">
vertical-default-position	"top" | "bottom" | "center" | "unset"	Default vertical position relative to anchor. Default: "unset"	<rapid-anchored-layout vertical-default-position="top">
vertical-viewport-lock	boolean	Controls whether the anchored region always remains fully in the viewport on the vertical axis. If true, the position is adjusted to stay within viewport bounds, detaching from the anchor if necessary. This prevents overflow and clipping. Default: false	<rapid-anchored-layout vertical-viewport-lock>
vertical-inset	boolean	Controls whether the region can overlap the anchor on the vertical axis	<rapid-anchored-layout vertical-inset>
vertical-threshold	number	Space threshold before the tallest area is selected for layout	<rapid-anchored-layout vertical-threshold="15">
vertical-scaling	"anchor" | "fill" | "content"	How height is calculated. Default: "content"	<rapid-anchored-layout vertical-scaling="fill">
fixed-placement	boolean	Controls whether the region uses fixed positioning instead of absolute. Default: false	<rapid-anchored-layout fixed-placement>
auto-update-mode	"anchor" | "auto"	Defines what triggers position reevaluation. Default: "anchor". anchor the component only updates its position when the anchor resizes, auto the component updates its position when: the anchor, window, or viewport resizes, any scroll in the document. Both update when update() is called.	<rapid-anchored-layout auto-update-mode="auto">

Properties

You should only read these properties via the code. Do not set them on the template.

Property	Type	Description
initialLayoutComplete	boolean	Indicates that an initial positioning pass on layout has completed
verticalPosition	"start" | "insetStart" | "insetEnd" | "end" | "center"	Indicates the current vertical position of the region. Depending on the axis start = left/top, end = right/bottom
horizontalPosition	"start" | "insetStart" | "insetEnd" | "end" | "center"	Indicates the current horizontal position of the region. Depending on the axis start = left/top, end = right/bottom

Slots

Slot	Description
Default	The elements that are contained in the anchored region.

Parts

This component doesn't have any css parts. Style the content directly in the default slot.

Events fired

Event	Type	Description	Example
loaded	this	Fires when the region is loaded and visible.	<rapid-anchored-region @loaded=${(x,ctx) => x.handleLoaded(ctx.event)}>
positionchange	this	Fires when the position has changed.	<rapid-anchored-region @positionchange=${(x,ctx) => x.handlePositionChange(ctx.event)}>

tip

Event type this means the event detail is a reference to the element itself.

Events listened to

This component doesn't listen to any events.