Anchored region

Anchored regions are containers which position content relative to the anchor element. The anchored region can react to the available space between the anchor and a parent "viewport" element such that the region is placed on the side of the anchor with the most available space, or even resize itself based on that space.

Use cases:

• Creating a layout which is reactive to layout changes
• Creating a layout where elements are not viewed in DOM order (1)

warning

(1) Elements which are viewed differently to the DOM order may 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. Default: ""	<rapid-anchored-layout anchor="header-id">
viewport	string	The HTML ID of the viewport element this region is positioned relative to. Default: ""	<rapid-anchored-layout viewport="main-content">
horizontal-positioning-mode	"uncontrolled" | "locktodefault" | "dynamic"	Sets logic for 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	Whether region remains in viewport on horizontal axis. Default: false	<rapid-anchored-layout horizontal-viewport-lock>
horizontal-inset	boolean	Whether region overlaps anchor on horizontal axis. Default: false	<rapid-anchored-layout horizontal-inset>
horizontal-threshold	number	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	Whether region remains in viewport on vertical axis (i.e. detatches from the anchor). Default: false	<rapid-anchored-layout vertical-viewport-lock>
vertical-inset	boolean	Whether the region overlaps the anchor on the vertical axis	<rapid-anchored-layout vertical-inset>
vertical-threshold	number	Space threshold before 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	Whether 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 be reading these properties via the code, rather than setting 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	This elements which are contained in the anchored region.

Parts

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

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.