Anchored position behavior

The getAnchoredPosition behavior and useAnchoredPosition hook are used to calculate the position of a "floating" element that is anchored to another DOM element. This is useful for implementing overlay UI, such as dialogs, popovers, tooltips, toasts, and dropdown-style menus.

At a high level, the getAnchoredPosition algorithm will attempt to find the most suitable position for the floating element based on the passed-in settings, its containing element, and the size and position of the anchor element. Specifically, the calculated position should try to ensure that the floating element, when positioned at the calculated coordinates, does not overflow or underflow the container's bounding box.

Settings for this behavior allow the user to customize several aspects of this calculation. See PositionSettings below for a detailed description of these settings.

Positioning algorithm

When calculating the position of the floating element, the algorithm relies on different measurements from three separate elements:

1. The floating element's width and height
2. The anchor element's x/y position and its width and height
3. The floating element's clipping container (for x/y position, width and height, and border sizes)

The public API only asks for the first two elements; the floating element's container is discovered via DOM traversal.

Finding the floating element's clipping container

The returned anchored position calculation is relative to the floating element's closest positioned ancestor. To find this ancestor, we try to check parents of the floating element until we find one that has a position set to anything other than static and use that element's bounding box as the container. If we can't find such an element, we will try to use document.body.

Once we have found the appropriate relative ancestor, we attempt to find the floating element's clipping container. The clipping container is an element that: 1) has overflow set to something other than visible, and 2) is either an ancestor of the relative ancestor, or is itself the relative ancestor. Again, if we cannot locate such an element, we will use document.body as the clipping container.

Once we have the clipping container, its bounding box is used as the viewport for the position calculation (see the next section). If the clipping container ends up being document.body, we take one additional step, allowing the clipping rectangle to be at least as tall as the window. This is done because the body element doesn't take up the full window size by default, but we still want to allow the entire space to be used as the viewport for the position calculation. It may be a good idea to ensure that this clipping container element also contains the anchor element and is scrollable. This will ensure that if scrolled, the anchor and floating element will move together.

Positioning and overflow

With the positions and sizes of the above DOM elements, the algorithm calculates the (x, y) coordinate for the floating element. Then, it checks to see if, based on the floating element's size, if it would overflow the bounds of the container. If it would, it does one of two things:

A) If the overflow happens in the same direction as the anchor side (e.g. side is 'outside-bottom' and the overflowing portion of the floating element is the bottom), try to find a different side, recalculate the position, and check for overflow again. If we check all four sides and don't find one that fits, revert to the bottom side, in hopes that a scrollbar might appear. B) Otherwise, adjust the alignment offset so that the floating element can stay inside the container's bounds.

For a more in-depth explanation of the positioning settings, see PositionSettings below.

Demo

Deploy Storybook to see a live demo of anchoredPosition.

Usage

const settings = {
  side: 'outside-right',
  align: 'center',
  alignmentOffset: 10,
  anchorOffset: -10,
} as Partial<PositionSettings>
const float = document.getElementById('floatingElement')
const anchor = document.getElementById('anchorElement')
const {top, left} = getAnchoredPosition(float, anchor, settings)
float.style.top = `${top}px`
float.style.left = `${left}px`

API

The getAnchoredPosition function takes the following arguments.

PositionSettings interface

PositionSettings is an object with the following interface

* If side is set to "inside-center", this defaults to 0 instead of 4.

** If using outside positioning, or if align is set to "center", this defaults to 0 instead of 4.

AnchorSide

AnchorSide can be any of the following strings:

'inside-top', 'inside-bottom', 'inside-left', 'inside-right', 'inside-center', 'outside-top', 'outside-bottom', 'outside-left', 'outside-right'

AnchorAlignment

AnchorAlignment can be any of the following strings:

'start', 'center', 'end'

Best practices

As discussed above, the positioning algorithm needs to first measure the size of three different elements. Therefore, all three of these elements (anchor element, floating element, and the floating element's closest positioned container) must be rendered at the time getAnchoredPosition is called. To avoid a frame where the floating element is rendered at the (0, 0) position, give it a style of visibility: hidden until its position is returned at set. This allows the element to be measured without showing up on the page.

A note on performance

Every time getAnchoredPosition is called, it causes a reflow because it needs to query the rendering engine for the positions of 3 elements: the anchor element, the floating element, and the closest ancestor of the floating element that is positioned. Therefore, this function should not be called until it is needed (e.g. an overlay-style menu is invoked and displayed).

useAnchoredPosition hook (private to @primer/react)

The useAnchoredPosition hook is used to provide anchored positioning data for React components. The hook returns refs that must be added to the anchor and floating elements, and a position object containing top and left. This position is tracked as state, so the component will re-render whenever it changes. It is the responsibility of the consumer to apply the top and left styles to the floating element in question.

Using your own refs

The useAnchoredPosition hook will return two refs for the anchor element and the floating element, which must be added to their respective JSX. If you would like to use your own refs, you can pass them into the hook as part of the settings object (see the interface below).

Recalculating position

Like other hooks such as useCallback and useEffect, this hook takes a dependencies array. If defined, the position will only be recalculated when one of the dependencies in this array changes. Otherwise, the position will be calculated when the component is first mounted, but never again.

useAnchoredPosition usage

export const AnchoredPositionExample = () => {
  const {floatingElementRef, anchorElementRef, position} = useAnchoredPosition({side: 'outside-bottom', align: 'center'})
  return (
    <div>
      <Box
        position="absolute"
        top={position?.top ?? 0}
        left={position?.left ?? 0}
        width={150}
        height={150}
        ref={floatingElementRef as React.RefObject<HTMLDivElement>}
      >
        Floating element
      </Box>
      <Box borderWidth='1px' borderStyle='solid' borderColor='border.default' borderRadius={2} width={400} height={75} ref={anchorElementRef as React.RefObject<HTMLDivElement>}>
        Anchor Element
      </Box>
    </div>
  )
}

useAnchoredPosition

Return value

AnchoredPositionHookSettings interface

AnchoredPositionHookSettings is an object with an interface that extends PositionSettings (see above). Additionally, it adds the following properties: