Ember Velcro sticks one element to another with Floating UI, it can be used as a modifier or a component.
Several of Floating UI's functions and middleware are used to create an experience out of the box that is useful and expected.
See Floating UI's documentation for more information on any of the following included functionality.
Functions:
computePosition - computes the x and y coordinates needed to anchor a floating element to a reference element.
autoUpdate - updates the x and y coordinates of the floating element so it remains anchored to the reference element when the page scrolls or when either the reference or floating elements are resized.
Middleware:
offset - the first of the middleware included; allows you to offset the floating element from the reference element by a given amount.
flip - flips the floating element to the opposite side of the reference element to keep it in view.
shift - shifts the floating element along the x or y axis to keep it in view
- x-axis for 'top' and 'bottom' placements
- y-axis for 'left' and 'right' placements
hide - hides the floating element when the reference element is no longer visible or when the floating element has escaped the reference element's clipping context.
@flipOptions- see flip docs for option values@middleware- array of one or more objects to add to the middleware array@offsetOptions- see offset docs for option values@placement- list of expected values@shiftOptions- see shift docs for option values@strategy- CSS position property, either 'fixed' or 'absolute'. Pros and cons of each strategy is here
@placement: 'bottom'@strategy: 'fixed'offset,flip, andshiftmiddleware all use their defaults.hidemiddleware uses bothreferenceHiddenandescapedoptions.
The Velcro component yields a single hash - 2 modifiers and 'velcro data':
velcro.data is the MiddlewareArguments object, it contains the following values:
- x
- y
- initialPlacement
- placement
- strategy
- middlewareData
- rects
- platform
- elements
See MiddlewareArguments for a description of each.
You can also use `velcro.setHook` yielded function for more complex composibility scenarios. Expand to read more.
Imagine you're writing a dropdown component with ember-velcro. You want to yield a trigger modifier that does two things:
- sets an element as the "hook" for ember-velcro
- attaches a click handler to toggle between the open/closed states
Without the yielded setHook function, this would not be possible. With setHook however, we can pass that function to the modifier, and the modifier can call that function with the element.
Such a dropdown component might look something like this:
let myModifier = modifier((element, [setHook, handler]) => {
// call ember-velcro's setHook
setHook(element);
// other custom logic
element.addEventListener('click', handler);
return () => {
element.removeEventListener('click', handler);
};
});
<template>
<Velcro as |velcro|>
{{yield (hash
trigger=(modifier myModifier velcro.setHook onClick)
)}}
</Velcro>
</template>This is needed because, at the time of writing, there's no way in ember to combine two existing modifiers into a single one. You can check the relevant pull request for more information.
- Ember.js v3.20 or above
- Ember CLI v3.20 or above
- Node.js v14 or above
npm install ember-velcro
# or
yarn add ember-velcro
# or
pnpm install ember-velcro
# or
ember install ember-velcro
Similar projects include:
The above projects both use Popper. In contrast, Ember Velcro uses Floating UI. Floating UI is the successor to Popper - see their migration guide for a complete comparison.
This project is licensed under the MIT License.