Add Floating UI functionality to Alpine 3.x components.
MIT License
Add Floating UI functionality to Alpine 3.x components.
This package only supports Alpine ^3.x.
This plugin adds a $float
magic and an x-float
directive to Alpine, with modifiers for Floating UI functionality.
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 install @awcodes/alpine-floating-ui
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.
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();
See the Floating UI Tutorial for infomation about styling.
$float
MagicTo 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
DirectiveTo 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>
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()],
}
$float
MagicTo use the default options for each middleware pass an empty object as the value.
<button @click="$float({
offset: 10,
flip: {},
hide: {
strategy: 'referenceHidden'
}
})"></button>
x-float
DirectiveAll 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'
}
}"
>
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.
$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>
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);
}
The second argument that can be passed to $float
is an object of plugin options for each float-ui element.
$float
Magic<button @click="$float({
offset: 10,
placement: 'bottom-start',
},{
trap: true
})"></button>
x-float
Directive<div
x-ref="panel"
class="panel"
x-float.trap
>
This projects follow the Semantic Versioning guidelines.
Copyright (c) 2022 Adam Weston and contributors
Licensed under the MIT license, see LICENSE.md for details.