Need help with alpine?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

alpinejs
12.0K Stars 462 Forks MIT License 1.1K Commits 27 Opened issues

Description

A rugged, minimal framework for composing JavaScript behavior in your markup.

Services available

!
?

Need anything else?

Contributors list

Alpine.js

npm bundle size npm version Chat

Alpine.js offers you the reactive and declarative nature of big frameworks like Vue or React at a much lower cost.

You get to keep your DOM, and sprinkle in behavior as you see fit.

Think of it like Tailwind for JavaScript.

Note: This tool's syntax is almost entirely borrowed from Vue (and by extension Angular). I am forever grateful for the gift they are to the web.

Translated documentation

| Language | Link for documentation | | --- | --- | | Chinese Traditional | 繁體中文說明文件 | | German | Dokumentation in Deutsch | | Indonesian | Dokumentasi Bahasa Indonesia | | Japanese | 日本語ドキュメント | | Portuguese | Documentação em Português | | Russian | Документация на русском | | Spanish | Documentación en Español |

Install

From CDN: Add the following script to the end of your

 section.
html

That's it. It will initialize itself.

For production environments, it's recommended to pin a specific version number in the link to avoid unexpected breakage from newer versions. For example, to use version

2.7.3
(latest):
html

From npm: Install the package from npm.

js
npm i alpinejs

Include it in your script.

js
import 'alpinejs'

For IE11 support Use the following scripts instead.

html


The pattern above is the module/nomodule pattern that will result in the modern bundle automatically loaded on modern browsers, and the IE11 bundle loaded automatically on IE11 and other legacy browsers.

Use

Dropdown/Modal ```html

Open Dropdown

    Dropdown Body

```

Tabs ```html

Foo Bar
Tab Foo
Tab Bar

```

You can even use it for non-trivial things: Pre-fetching a dropdown's HTML content on hover. ```html

response.text()) .then(html => { $refs.dropdown.innerHTML = html }) " @click="open = true" >Show Dropdown
Loading Spinner...

```

Learn

There are 14 directives available to you:

| Directive | Description | | --- | --- | |

x-data
| Declares a new component scope. | |
x-init
| Runs an expression when a component is initialized. | |
x-show
| Toggles

display: none;
on the element depending on expression (true or false). | |
x-bind
| Sets the value of an attribute to the result of a JS expression. | |
x-on
| Attaches an event listener to the element. Executes JS expression when emitted. | |
x-model
| Adds "two-way data binding" to an element. Keeps input element in sync with component data. | |
x-text
| Works similarly to
x-bind
, but will update the
innerText
of an element. | |
x-html
| Works similarly to
x-bind
, but will update the
innerHTML
of an element. | |
x-ref
| Convenient way to retrieve raw DOM elements out of your component. | |
x-if
| Remove an element completely from the DOM. Needs to be used on a
 tag. |
| 
x-for
| Create new DOM nodes for each item in an array. Needs to be used on a
 tag. |
| 
x-transition
| Directives for applying classes to various stages of an element's transition. | |
x-spread
| Allows you to bind an object of Alpine directives to an element for better reusability. | |
x-cloak
| This attribute is removed when Alpine initializes. Useful for hiding pre-initialized DOM. |

And 6 magic properties:

| Magic Properties | Description | | --- | --- | |

$el
| Retrieve the root component DOM node. | |
$refs
| Retrieve DOM elements marked with

x-ref
inside the component. | |
$event
| Retrieve the native browser "Event" object within an event listener. | |
$dispatch
| Create a
CustomEvent
and dispatch it using
.dispatchEvent()
internally. | |
$nextTick
| Execute a given expression AFTER Alpine has made its reactive DOM updates. | |
$watch
| Will fire a provided callback when a component property you "watched" gets changed. |

Sponsors

Tailwind CSS

Want your logo here? DM on Twitter

Community Projects

Directives


x-data

Example:

...

Structure:

...

x-data
declares a new component scope. It tells the framework to initialize a new component with the following data object.

Think of it like the

data
property of a Vue component.

Extract Component Logic

You can extract data (and behavior) into reusable functions:

Open
<div x-show="isOpen()" x-on:click.away="close">
    // Dropdown
</div>

For bundler users, note that Alpine.js accesses functions that are in the global scope (

window
), you'll need to explicitly assign your functions to
window
in order to use them with
x-data
for example
window.dropdown = function () {}
(this is because with Webpack, Rollup, Parcel etc.
function
's you define will default to the module's scope not
window
).

You can also mix-in multiple data objects using object destructuring:


x-init

Example:

Structure:

x-init
runs an expression when a component is initialized.

If you wish to run code AFTER Alpine has made its initial updates to the DOM (something like a

mounted()
hook in VueJS), you can return a callback from
x-init
, and it will be run after:

x-init="() => { // we have access to the post-dom-initialization state here // }"

x-show

Example:

Structure:

x-show
toggles the
display: none;
style on the element depending if the expression resolves to
true
or
false
.

x-show.transition

x-show.transition
is a convenience API for making your
x-show
s more pleasant using CSS transitions.
These contents will be transitioned in and out.

| Directive | Description | | --- | --- | |

x-show.transition
| A simultaneous fade and scale. (opacity, scale: 0.95, timing-function: cubic-bezier(0.4, 0.0, 0.2, 1), duration-in: 150ms, duration-out: 75ms) |
x-show.transition.in
| Only transition in. | |
x-show.transition.out
| Only transition out. | |
x-show.transition.opacity
| Only use the fade. | |
x-show.transition.scale
| Only use the scale. | |
x-show.transition.scale.75
| Customize the CSS scale transform
transform: scale(.75)
. | |
x-show.transition.duration.200ms
| Sets the "in" transition to 200ms. The out will be set to half that (100ms). | |
x-show.transition.origin.top.right
| Customize the CSS transform origin
transform-origin: top right
. | |
x-show.transition.in.duration.200ms.out.duration.50ms
| Different durations for "in" and "out". |

Note: All of these transition modifiers can be used in conjunction with each other. This is possible (although ridiculous lol):

x-show.transition.in.duration.100ms.origin.top.right.opacity.scale.85.out.duration.200ms.origin.bottom.left.opacity.scale.95

Note:

x-show
will wait for any children to finish transitioning out. If you want to bypass this behavior, add the
.immediate
modifer: ```html

```

x-bind

Note: You are free to use the shorter ":" syntax:

:type="..."
.

Example:



Structure:



x-bind
sets the value of an attribute to the result of a JavaScript expression. The expression has access to all the keys of the component's data object, and will update every-time its data is updated.

Note: attribute bindings ONLY update when their dependencies update. The framework is smart enough to observe data changes and detect which bindings care about them.

x-bind
for class attributes

x-bind
behaves a little differently when binding to the
class
attribute.

For classes, you pass in an object whose keys are class names, and values are boolean expressions to determine if those class names are applied or not.

For example:

In this example, the "hidden" class will only be applied when the value of the

foo
data attribute is
true
.

x-bind
for boolean attributes

x-bind
supports boolean attributes in the same way as value attributes, using a variable as the condition or any JavaScript expression that resolves to
true
or
false
.

For example: ```html <!-- Given: --> Click me

Click me

Click me ```

This will add or remove the

disabled
attribute when
myVar
is true or false respectively.

Boolean attributes are supported as per the HTML specification, for example

disabled
,
readonly
,
required
,
checked
,
hidden
,
selected
,
open
, etc.

Note: If you need a false state to show for your attribute, such as

aria-*
, chain
.toString()
to the value while binding to the attribute. For example:
:aria-expanded="isOpen.toString()"
would persist whether
isOpen
was
true
or
false
.

.camel
modifier Example:



The

camel
modifier will bind to the camel case equivalent of the attribute name. In the example above, the value of
viewBox
will be bound the
viewBox
attribute as opposed to the
view-box
attribute.

x-on

Note: You are free to use the shorter "@" syntax:

@click="..."
.

Example:



Structure:



x-on
attaches an event listener to the element it's declared on. When that event is emitted, the JavaScript expression set as its value is executed. You can use
x-on
with any event available for the element you're adding the directive on, for a full list of events, see the Event reference on MDN for a list of possible values.

If any data is modified in the expression, other element attributes "bound" to this data, will be updated.

Note: You can also specify a JavaScript function name.

Example:



This is equivalent to:



keydown
modifiers

Example:



You can specify specific keys to listen for using keydown modifiers appended to the

x-on:keydown
directive. Note that the modifiers are kebab-cased versions of
Event.key
values.

Examples:

enter
,
escape
,
arrow-up
,
arrow-down

Note: You can also listen for system-modifier key combinations like:

x-on:keydown.cmd.enter="foo"

.away
modifier

Example:

When the

.away
modifier is present, the event handler will only be executed when the event originates from a source other than itself, or its children.

This is useful for hiding dropdowns and modals when a user clicks away from them.

.prevent
modifier Example:



Adding

.prevent
to an event listener will call
preventDefault
on the triggered event. In the above example, this means the checkbox wouldn't actually get checked when a user clicks on it.

.stop
modifier Example:

Adding

.stop
to an event listener will call
stopPropagation
on the triggered event. In the above example, this means the "click" event won't bubble from the button to the outer
. Or in other words, when a user clicks the button,
foo
won't be set to
'bar'
.

.self
modifier Example:

Adding

.self
to an event listener will only trigger the handler if the
$event.target
is the element itself. In the above example, this means the "click" event that bubbles from the button to the outer
will not run the handler.

.window
modifier Example:

Adding

.window
to an event listener will install the listener on the global window object instead of the DOM node on which it is declared. This is useful for when you want to modify component state when something changes with the window, like the resize event. In this example, when the window grows larger than 768 pixels wide, we will close the modal/dropdown, otherwise maintain the same state.

Note: You can also use the

.document
modifier to attach listeners to
document
instead of
window

.once
modifier Example:



Adding the

.once
modifier to an event listener will ensure that the listener will only be handled once. This is useful for things you only want to do once, like fetching HTML partials and such.

.passive
modifier Example:



Adding the

.passive
modifier to an event listener will make the listener a passive one, which means
preventDefault()
will not work on any events being processed, this can help, for example with scroll performance on touch devices.

.debounce
modifier Example:



The

debounce
modifier allows you to "debounce" an event handler. In other words, the event handler will NOT run until a certain amount of time has elapsed since the last event that fired. When the handler is ready to be called, the last handler call will execute.

The default debounce "wait" time is 250 milliseconds.

If you wish to customize this, you can specify a custom wait time like so:


.camel
modifier Example:



The

camel
modifier will attach an event listener for the camel case equivalent event name. In the example above, the expression will be evaluated when the
eventName
event is fired on the element.

x-model

Example:



Structure:



x-model
adds "two-way data binding" to an element. In other words, the value of the input element will be kept in sync with the value of the data item of the component.

Note:

x-model
is smart enough to detect changes on text inputs, checkboxes, radio buttons, textareas, selects, and multiple selects. It should behave how Vue would in those scenarios.

.number
modifier Example:



The

number
modifier will convert the input's value to a number. If the value cannot be parsed as a valid number, the original value is returned.

.debounce
modifier Example:



The

debounce
modifier allows you to add a "debounce" to a value update. In other words, the event handler will NOT run until a certain amount of time has elapsed since the last event that fired. When the handler is ready to be called, the last handler call will execute.

The default debounce "wait" time is 250 milliseconds.

If you wish to customize this, you can specifiy a custom wait time like so:



x-text

Example:

Structure:



x-text
works similarly to
x-bind
, except instead of updating the value of an attribute, it will update the
innerText
of an element.

x-html

Example:

Structure:



x-html
works similarly to
x-bind
, except instead of updating the value of an attribute, it will update the
innerHTML
of an element.

:warning: Only use on trusted content and never on user-provided content. :warning:

Dynamically rendering HTML from third parties can easily lead to XSS vulnerabilities.


x-ref

Example:

Structure:

x-ref
provides a convenient way to retrieve raw DOM elements out of your component. By setting an
x-ref
attribute on an element, you are making it available to all event handlers inside an object called
$refs
.

This is a helpful alternative to setting ids and using

document.querySelector
all over the place.

Note: you can also bind dynamic values for x-ref:

if you need to.

x-if

Example:



Structure:



For cases where

x-show
isn't sufficient (
x-show
sets an element to
display: none
if it's false),
x-if
can be used to actually remove an element completely from the DOM.

It's important that

x-if
is used on a
 tag because Alpine doesn't use a virtual DOM. This implementation allows Alpine to stay rugged and use the real DOM to work its magic.

Note:

x-if
must have a single element root inside the
 tag.

Note: When using

template
in a
svg
tag, you need to add a polyfill that should be run before Alpine.js is initialized.

x-for

Example:

html

Note: the

:key
binding is optional, but HIGHLY recommended.

x-for
is available for cases when you want to create new DOM nodes for each item in an array. This should appear similar to
v-for
in Vue, with one exception of needing to exist on a
template
tag, and not a regular DOM element.

If you want to access the current index of the iteration, use the following syntax:


If you want to access the array object (collection) of the iteration, use the following syntax:


Note:

x-for
must have a single element root inside of the
 tag.

Note: When using

template
in a
svg
tag, you need to add a polyfill that should be run before Alpine.js is initialized.

Nesting
x-for
s

You can nest

x-for
loops, but you MUST wrap each loop in an element. For example:

Iterating over a range

Alpine supports the

i in n
syntax, where
n
is an integer, allowing you to iterate over a fixed range of elements.


x-transition

Example: ```html <div x-show="open" x-transition:enter="transition ease-out duration-300" x-transition:enter-start="opacity-0 transform scale-90" x-transition:enter-end="opacity-100 transform scale-100" x-transition:leave="transition ease-in duration-300" x-transition:leave-start="opacity-100 transform scale-100" x-transition:leave-end="opacity-0 transform scale-90"

...

```

The example above uses classes from Tailwind CSS.

Alpine offers 6 different transition directives for applying classes to various stages of an element's transition between "hidden" and "shown" states. These directives work both with

x-show
AND
x-if
.

These behave exactly like VueJS's transition directives, except they have different, more sensible names:

| Directive | Description | | --- | --- | |

:enter
| Applied during the entire entering phase. | |
:enter-start
| Added before element is inserted, removed one frame after element is inserted. | |
:enter-end
| Added one frame after element is inserted (at the same time
enter-start
is removed), removed when transition/animation finishes. |
:leave
| Applied during the entire leaving phase. | |
:leave-start
| Added immediately when a leaving transition is triggered, removed after one frame. | |
:leave-end
| Added one frame after a leaving transition is triggered (at the same time
leave-start
is removed), removed when the transition/animation finishes.

x-spread

Example: ```html

Open Dropdown
Dropdown Contents

`x-spread` allows you to extract an element's Alpine bindings into a reusable object.

The object keys are the directives (Can be any directive including modifiers), and the values are callbacks to be evaluated by Alpine.

> Note: There are a couple of caveats to x-spread:
> - When the directive being "spread" is `x-for`, you should return a normal expression string from the callback. For example: `['x-for']() { return 'item in items' }`.
> - `x-data` and `x-init` can't be used inside a "spread" object.

---

### `x-cloak`
**Example:** `
` `x-cloak` attributes are removed from elements when Alpine initializes. This is useful for hiding pre-initialized DOM. It's typical to add the following global style for this to work: ```html

Magic Properties

With the exception of

$el
, magic properties are not available within
x-data
as the component isn't initialized yet.

$el

Example:

html
Replace me with "foo"

$el
is a magic property that can be used to retrieve the root component DOM node.

$refs

Example: ```html

```

$refs
is a magic property that can be used to retrieve DOM elements marked with
x-ref
inside the component. This is useful when you need to manually manipulate DOM elements.

$event

Example:

html

$event
is a magic property that can be used within an event listener to retrieve the native browser "Event" object.

Note: The $event property is only available in DOM expressions.

If you need to access $event inside of a JavaScript function you can pass it in directly:




$dispatch

Example:

html

Note on Event Propagation

Notice that, because of event bubbling, when you need to capture events dispatched from nodes that are under the same nesting hierarchy, you'll need to use the

.window
modifier:

Example:

This won't work because when

custom-event
is dispatched, it'll propagate to its common ancestor, the
div
.

Dispatching to Components

You can also take advantage of the previous technique to make your components talk to each other:

Example:

$dispatch
is a shortcut for creating a
CustomEvent
and dispatching it using
.dispatchEvent()
internally. There are lots of good use cases for passing data around and between components using custom events. Read here for more information on the underlying
CustomEvent
system in browsers.

You will notice that any data passed as the second parameter to

$dispatch('some-event', { some: 'data' })
, becomes available through the new events "detail" property:
$event.detail.some
. Attaching custom event data to the
.detail
property is standard practice for
CustomEvent
s in browsers. Read here for more info.

You can also use

$dispatch()
to trigger data updates for
x-model
bindings. For example:

Note: The $dispatch property is only available in DOM expressions.

If you need to access $dispatch inside of a JavaScript function you can pass it in directly:




$nextTick

Example:

html

$nextTick
is a magic property that allows you to only execute a given expression AFTER Alpine has made its reactive DOM updates. This is useful for times you want to interact with the DOM state AFTER it's reflected any data updates you've made.

$watch

Example:

html
Toggle Open

You can "watch" a component property with the

$watch
magic method. In the above example, when the button is clicked and
open
is changed, the provided callback will fire and
console.log
the new value.

Security

If you find a security vulnerability, please send an email to [email protected].

Alpine relies on a custom implementation using the

Function
object to evaluate its directives. Despite being more secure then
eval()
, its use is prohibited in some environments, such as Google Chrome App, using restrictive Content Security Policy (CSP).

If you use Alpine in a website dealing with sensitive data and requiring CSP, you need to include

unsafe-eval
in your policy. A robust policy correctly configured will help protecting your users when using personal or financial data.

Since a policy applies to all scripts in your page, it's important that other external libraries included in the website are carefully reviewed to ensure that they are trustworthy and they won't introduce any Cross Site Scripting vulnerability either using the

eval()
function or manipulating the DOM to inject malicious code in your page.

V3 Roadmap

  • Move from
    x-ref
    to
    ref
    for Vue parity?
  • Add
    Alpine.directive()
  • Add
    Alpine.component('foo', {...})
    (With magic
    __init()
    method)
  • Dispatch Alpine events for "loaded", "transition-start", etc... (#299) ?
  • Remove "object" (and array) syntax from
    x-bind:class="{ 'foo': true }"
    (#236 to add support for object syntax for the
    style
    attribute)
  • Improve
    x-for
    mutation reactivity (#165)
  • Add "deep watching" support in V3 (#294)
  • Add
    $el
    shortcut
  • Change
    @click.away
    to
    @click.outside
    ?

License

Copyright © 2019-2020 Caleb Porzio and contributors

Licensed under the MIT license, see LICENSE.md for details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.