Position a dropdown element near a button in a way that fits on the screen.
npm install 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.
``js`
import { containByScreen } from "contain-by-screen";
Moves the target element to be positioned next to the anchor element basedoptions
on the given . Returns a "Choice" object that may be used as theoptions 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.
`js`
import { getContainByScreenResults } from "contain-by-screen";
Works like containByScreen, but instead of positioning the element and{choice, coordinates}
returning a Choice object, this function does not mutate the element at all, and
instead returns a object where the coordinates
property is an object with and right` properties specifying where to
position the target element.
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.
TypeScript type definitions for this module
are included! The type definitions won't require any configuration to use.