contain-by-screen

contain-by-screen

This function is for positioning an element next to another in a way that fits on the screen. This can be used to position a dropdown menu next to a button. You can pass an argument to make containByScreen prefer to put the dropdown menu below the button, and if there isn't enough room below the button, then the menu will be positioned next to or above the button automatically instead.

This module can be used in Browsers via a bundler such as Webpack or Browserify.

API

containByScreen(target, anchor, options): Choice

import { containByScreen } from "contain-by-screen";

Moves the target element to be positioned next to the anchor element based on the given options. Returns a "Choice" object that may be used as the options parameter to other calls to containByScreen to position another element consistently with a previous call.

target is the element to position, such as a dropdown menu. The element must have its CSS position property set to "fixed".

anchor is the element to position the target relative to. This would usually be the button that triggered a dropdown menu to appear.

options is an object that may have the following optional properties:

• position sets the prioritized position for the target relative to its anchor. It may be set to null, "top", "bottom", "left", "right", "cover", or an array of some of those string values. The element will attempt to use this position (or each value in the array in order) unless it is not possible to do so while fitting the element on-screen.

• forcePosition is a boolean which controls whether the configured position value will be used even if it results in the element going off of the screen.

• hAlign sets the prioritized horizontal alignment mode for the element relative to its anchor. The horizontal alignment mode is used if the element is positioned in the top, bottom, or cover positions relative to the anchor, and causes the element to be moved horizontally in order to make a specific edge align. It may be set to null, "center", "left", "right", "unaligned", or an array of some of those string values. The element will attempt to use this alignment (or each value in the array in order) unless it is not possible to do so while fitting the element on-screen.

• forceHAlign is a boolean which controls whether the configured hAlign value will be used even if it results in the element going off of the screen.

• vAlign sets the prioritized vertical alignment mode for the element relative to its anchor. The vertical alignment mode is used if the element is positioned in the left, right, or cover positions relative to the anchor, and causes the element to be moved vertically in order to make a specific edge align. It may be set to null, "center", "top", "bottom", "unaligned", or an array of some of those string values. The element will attempt to use this alignment (or each value in the array in order) unless it is not possible to do so while fitting the element on-screen.

• forceVAlign is a boolean which controls whether the configured vAlign value will be used even if it results in the element going off of the screen.

• buffer specifies a number of pixels to be used as a buffer zone around the target. For screen-fitting purposes, the target will be treated as if it was this much larger in all directions, requiring it to be placed with the given amount of space away from the anchor element (when position is not "cover") and the edges of the screen. The buffer option is useful if the element has children which are positioned such that they escape the boundaries of the element. Buffers do not affect alignment with the anchor element.

• topBuffer, bottomBuffer, leftBuffer, and rightBuffer specify an additional buffer space for a specific edge.

getContainByScreenResults(target, anchor, options): ChoiceAndCoordinates

import { getContainByScreenResults } from "contain-by-screen";

Works like containByScreen, but instead of positioning the element and returning a Choice object, this function does not mutate the element at all, and instead returns a {choice, coordinates} object where the coordinates property is an object with left and right properties specifying where to position the target element.

Related

The project react-float-anchor is a React wrapper around this function, and react-menu-list is a library that uses it for building interactive menus.

Types

TypeScript type definitions for this module are included! The type definitions won't require any configuration to use.

Changelog

2.1.0 (2023-09-29)

• Fixed issue where large elements could fail to be positioned onscreen #17.
• Added new "unaligned" value for hAlign and vAlign options.