@awcodes/alpine-floating-ui
v3.6.3
Published
Add Floating UI functionality to Alpine 3.x components.
Downloads
7,314
Readme
Alpine Floating UI
Add Floating UI functionality to Alpine 3.x components.
This package only supports Alpine ^3.x.
About
This plugin adds a $float magic and an x-float directive to Alpine, with modifiers for Floating UI functionality.
Installation
CDN
Include the following <script> tag in the <head> of your document, just before Alpine. This plugin has the option to use x-trap, but you must also include the Alpine Focus plugin as well to make use of it.
<script src="https://cdn.jsdelivr.net/npm/@awcodes/[email protected]/dist/cdn.min.js" defer></script>
<!-- optional unless you want to use x-trap -->
<script defer src="https://unpkg.com/@alpinejs/[email protected]/dist/cdn.min.js"></script>NPM
npm install @awcodes/alpine-floating-uiThis plugin has the option to use x-trap, but you must also include the Alpine Focus plugin as well to make use of it.
import Alpine from "alpinejs";
import Focus from "@alpinejs/focus"; // optional unless you want to use x-trap
import AlpineFloatingUI from "@awcodes/alpine-floating-ui";
Alpine.plugin(Focus); // optional unless you want to use x-trap
Alpine.plugin(AlpineFloatingUI);
window.Alpine = Alpine;
window.Alpine.start();CSS
See the Floating UI Tutorial for infomation about styling.
Usage
$float Magic
To create a Floating UI component, use the $float magic on the trigger element and apply an x-ref to your 'panel'. Don't forget to have x-data on the root element of your component.
<style>
.panel { display: none; }
</style>
<div class="component" x-data>
<button @click="$float()">I have a floating panel. Woot!</button>
<div x-ref="panel" class="panel">I'm floating</div>
</div>x-float Directive
To create a floating UI component with x-float, add the directive to your floating element with an x-ref to name the name. You can then trigger the panel with a click event using $refs to target the panel.
Available methods on the trigger are toggle, open, and close.
To use the middleware with x-float simply chain on the middleware you need to use.
<div class="component" x-data>
<button @click="$refs.panel.toggle">Trigger</button>
<div x-ref="panel" class="panel" x-float.placement.bottom-start.flip.offset>
<p>I'm floating</p>
</div>
</div>Floating UI configuration
The first argument of $float should be an object.
This object currently accepts the 'position', 'flip', 'offset', 'shift', 'arrow', and 'hide' middleware for Floating UI. See the Floating UI Tutorial for infomation about these options.
Default options are:
{
placement: 'bottom',
middleware: [autoPlacement()],
}With $float Magic
To use the default options for each middleware pass an empty object as the value.
<button @click="$float({
offset: 10,
flip: {},
hide: {
strategy: 'referenceHidden'
}
})"></button>With x-float Directive
All settings should be configured within the expression of the x-float directive with the exception of placement which should be used directly on the directive itself. See https://floating-ui.com/docs/computePosition#placement placement options.
<div
x-ref="panel"
class="panel"
x-float.placement.top.flip.offset.hide="{
offset: 30,
hide: {
strategy: 'referenceHidden'
}
}"
>Arrow Middleware
To use the arrow middleware you must provide an element to use as the arrow, placed inside your panel in the HTML and passed into the arrow middleware as a $ref to the element.
With $float Magic
<div class="component" x-data>
<button @click="$float({
offset: 10,
arrow: {
element: $refs.arrow
}
})">I'm a fancy button with a fancy arrow panel</button>
<div x-ref="panel" class="panel">
I'm floating 2!
<div x-ref="arrow" class="arrow"></div>
</div>
</div>With x-float Directive
<div class="component" x-data>
<button @click="$refs.panel.toggle">I'm a fancy button with a fancy arrow panel</button>
<div
x-ref="panel"
class="panel"
x-float.flip.offset.trap.arrow="{
offset: 30,
arrow: {
element: $refs.arrow
}
}"
>
<p>I'm floating 2!</p>
<div x-ref="arrow" class="arrow"></div>
</div>
</div>Styling the arrow (this is just an example, you are free to style it anyway you choose):
.arrow {
position: absolute;
background-color: inherit;
width: 8px;
height: 8px;
transform: rotate(45deg);
}X-Trap
The second argument that can be passed to $float is an object of plugin options for each float-ui element.
With $float Magic
<button @click="$float({
offset: 10,
placement: 'bottom-start',
},{
trap: true
})"></button>With x-float Directive
<div
x-ref="panel"
class="panel"
x-float.trap
>Versioning
This projects follow the Semantic Versioning guidelines.
License
Copyright (c) 2022 Adam Weston and contributors
Licensed under the MIT license, see LICENSE.md for details.