Notice: This Plugin was previously called "Trap". Trap's functionality has been absorbed into this plugin along with additional functionality. You can swap Trap for Focus without any breaking changes.

Focus Plugin

Alpine's Focus plugin allows you to manage focus on a page.

This plugin internally makes heavy use of the open source tool: Tabbable. Big thanks to that team for providing a much needed solution to this problem.

Installation

You can use this plugin by either including it from a <script> tag or installing it via NPM:

Via CDN

You can include the CDN build of this plugin as a <script> tag, just make sure to include it BEFORE Alpine's core JS file.

<!-- Alpine Plugins -->
<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/[email protected]/dist/cdn.min.js"></script>
 
<!-- Alpine Core -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"></script>

<!-- Alpine Plugins -->
<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/[email protected]/dist/cdn.min.js"></script>

<!-- Alpine Core -->
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"></script>

Via NPM

You can install Focus from NPM for use inside your bundle like so:

npm install @alpinejs/focus

npm install @alpinejs/focus

Then initialize it from your bundle:

import Alpine from 'alpinejs'
import focus from '@alpinejs/focus'
 
Alpine.plugin(focus)
 
...

import Alpine from 'alpinejs'
import focus from '@alpinejs/focus'

Alpine.plugin(focus)

...

x-trap

Focus offers a dedicated API for trapping focus within an element: the x-trap directive.

x-trap accepts a JS expression. If the result of that expression is true, then the focus will be trapped inside that element until the expression becomes false, then at that point, focus will be returned to where it was previously.

For example:

<div x-data="{ open: false }">
    <button @click="open = true">Open Dialog</button>
 
    <span x-show="open" x-trap="open">
        <p>...</p>
 
        <input type="text" placeholder="Some input...">
 
        <input type="text" placeholder="Some other input...">
 
        <button @click="open = false">Close Dialog</button>
    </span>
</div>

<div x-data="{ open: false }">
    <button @click="open = true">Open Dialog</button>

    <span x-show="open" x-trap="open">
        <p>...</p>

        <input type="text" placeholder="Some input...">

        <input type="text" placeholder="Some other input...">

        <button @click="open = false">Close Dialog</button>
    </span>
</div>

Focus is now "trapped" inside this dialog, meaning you can only click/focus elements within this yellow dialog. If you press tab repeatedly, the focus will stay within this dialog.

Nesting dialogs

Sometimes you may want to nest one dialog inside another. x-trap makes this trivial and handles it automatically.

x-trap keeps track of newly "trapped" elements and stores the last actively focused element. Once the element is "untrapped" then the focus will be returned to where it was originally.

This mechanism is recursive, so you can trap focus within an already trapped element infinite times, then "untrap" each element successively.

Here is nesting in action:

<div x-data="{ open: false }">
    <button @click="open = true">Open Dialog</button>
 
    <span x-show="open" x-trap="open">
 
        ...
 
        <div x-data="{ open: false }">
            <button @click="open = true">Open Nested Dialog</button>
 
            <span x-show="open" x-trap="open">
 
                ...
 
                <button @click="open = false">Close Nested Dialog</button>
            </span>
        </div>
 
        <button @click="open = false">Close Dialog</button>
    </span>
</div>

<div x-data="{ open: false }">
    <button @click="open = true">Open Dialog</button>

    <span x-show="open" x-trap="open">

        ...

        <div x-data="{ open: false }">
            <button @click="open = true">Open Nested Dialog</button>

            <span x-show="open" x-trap="open">

                ...

                <button @click="open = false">Close Nested Dialog</button>
            </span>
        </div>

        <button @click="open = false">Close Dialog</button>
    </span>
</div>

Focus is now "trapped" inside this nested dialog. You cannot focus anything inside the outer dialog while this is open. If you close this dialog, focus will be returned to the last known active element.

Modifiers

.inert

When building things like dialogs/modals, it's recommended to hide all the other elements on the page from screen readers when trapping focus.

By adding .inert to x-trap, when focus is trapped, all other elements on the page will receive aria-hidden="true" attributes, and when focus trapping is disabled, those attributes will also be removed.

<!-- When `open` is `false`: -->
<body x-data="{ open: false }">
    <div x-trap.inert="open" ...>
        ...
    </div>
 
    <div>
        ...
    </div>
</body>
 
<!-- When `open` is `true`: -->
<body x-data="{ open: true }">
    <div x-trap.inert="open" ...>
        ...
    </div>
 
    <div aria-hidden="true">
        ...
    </div>
</body>

<!-- When `open` is `false`: -->
<body x-data="{ open: false }">
    <div x-trap.inert="open" ...>
        ...
    </div>

    <div>
        ...
    </div>
</body>

<!-- When `open` is `true`: -->
<body x-data="{ open: true }">
    <div x-trap.inert="open" ...>
        ...
    </div>

    <div aria-hidden="true">
        ...
    </div>
</body>

.noscroll

When building dialogs/modals with Alpine, it's recommended that you disable scrolling for the surrounding content when the dialog is open.

x-trap allows you to do this automatically with the .noscroll modifiers.

By adding .noscroll, Alpine will remove the scrollbar from the page and block users from scrolling down the page while a dialog is open.

For example:

<div x-data="{ open: false }">
    <button>Open Dialog</button>
 
    <div x-show="open" x-trap.noscroll="open">
        Dialog Contents
 
        <button @click="open = false">Close Dialog</button>
    </div>
</div>

<div x-data="{ open: false }">
    <button>Open Dialog</button>

    <div x-show="open" x-trap.noscroll="open">
        Dialog Contents

        <button @click="open = false">Close Dialog</button>
    </div>
</div>

Dialog Contents

Notice how you can no longer scroll on this page while this dialog is open.

.noreturn

Sometimes you may not want focus to be returned to where it was previously. Consider a dropdown that's triggered upon focusing an input, returning focus to the input on close will just trigger the dropdown to open again.

x-trap allows you to disable this behavior with the .noreturn modifier.

By adding .noreturn, Alpine will not return focus upon x-trap evaluating to false.

For example:

<div x-data="{ open: false }" x-trap.noreturn="open">
    <input type="search" placeholder="search for something" />
 
    <div x-show="open">
        Search results
 
        <button @click="open = false">Close</button>
    </div>
</div>

<div x-data="{ open: false }" x-trap.noreturn="open">
    <input type="search" placeholder="search for something" />

    <div x-show="open">
        Search results

        <button @click="open = false">Close</button>
    </div>
</div>

Search results

Notice when closing this dropdown, focus is not returned to the input.

.noautofocus

By default, when x-trap traps focus within an element, it focuses the first focussable element within that element. This is a sensible default, however there are times where you may want to disable this behavior and not automatically focus any elements when x-trap engages.

By adding .noautofocus, Alpine will not automatically focus any elements when trapping focus.

$focus

This plugin offers many smaller utilities for managing focus within a page. These utilities are exposed via the $focus magic.

Property	Description
`focus(el)`	Focus the passed element (handling annoyances internally: using nextTick, etc.)
`focusable(el)`	Detect whether or not an element is focusable
`focusables()`	Get all "focusable" elements within the current element
`focused()`	Get the currently focused element on the page
`lastFocused()`	Get the last focused element on the page
`within(el)`	Specify an element to scope the `$focus` magic to (the current element by default)
`first()`	Focus the first focusable element
`last()`	Focus the last focusable element
`next()`	Focus the next focusable element
`previous()`	Focus the previous focusable element
`noscroll()`	Prevent scrolling to the element about to be focused
`wrap()`	When retrieving "next" or "previous" use "wrap around" (ex. returning the first element if getting the "next" element of the last element)
`getFirst()`	Retrieve the first focusable element
`getLast()`	Retrieve the last focusable element
`getNext()`	Retrieve the next focusable element
`getPrevious()`	Retrieve the previous focusable element

Let's walk through a few examples of these utilities in use. The example below allows the user to control focus within the group of buttons using the arrow keys. You can test this by clicking on a button, then using the arrow keys to move focus around:

<div
    @keydown.right="$focus.next()"
    @keydown.left="$focus.previous()"
>
    <button>First</button>
    <button>Second</button>
    <button>Third</button>
</div>

<div
    @keydown.right="$focus.next()"
    @keydown.left="$focus.previous()"
>
    <button>First</button>
    <button>Second</button>
    <button>Third</button>
</div>

(Click a button, then use the arrow keys to move left and right)

Notice how if the last button is focused, pressing "right arrow" won't do anything. Let's add the .wrap() method so that focus "wraps around":

<div
    @keydown.right="$focus.wrap().next()"
    @keydown.left="$focus.wrap().previous()"
>
    <button>First</button>
    <button>Second</button>
    <button>Third</button>
</div>

<div
    @keydown.right="$focus.wrap().next()"
    @keydown.left="$focus.wrap().previous()"
>
    <button>First</button>
    <button>Second</button>
    <button>Third</button>
</div>

(Click a button, then use the arrow keys to move left and right)

Now, let's add two buttons, one to focus the first element in the button group, and another focus the last element:

<button @click="$focus.within($refs.buttons).first()">Focus "First"</button>
<button @click="$focus.within($refs.buttons).last()">Focus "Last"</button>
 
<div
    x-ref="buttons"
    @keydown.right="$focus.wrap().next()"
    @keydown.left="$focus.wrap().previous()"
>
    <button>First</button>
    <button>Second</button>
    <button>Third</button>
</div>

<button @click="$focus.within($refs.buttons).first()">Focus "First"</button>
<button @click="$focus.within($refs.buttons).last()">Focus "Last"</button>

<div
    x-ref="buttons"
    @keydown.right="$focus.wrap().next()"
    @keydown.left="$focus.wrap().previous()"
>
    <button>First</button>
    <button>Second</button>
    <button>Third</button>
</div>

Notice that we needed to add a .within() method for each button so that $focus knows to scope itself to a different element (the div wrapping the buttons).

← Persist

Collapse →

Code highlighting provided by Torchlight