Quick Start Guide

Get up and running with Alpine Components in minutes.

1. Install

npm install alpine-components alpinejs

2. Choose an integration style

Alpine Components ships as ESM/CJS for bundlers and an IIFE build for script tags.

Module (bundler) style

// main.js
import Alpine from 'alpinejs';
import { AlpineComponent, AlpineComponentPlugin } from 'alpine-components';

// Register your components
AlpineComponent.register('modal', 'modal/modal.html', 'modal/modal.js');

// Use the plugin
Alpine.plugin(AlpineComponentPlugin);
Alpine.start();

Script tag (no bundler) style

Use the prebuilt IIFE bundle from a CDN (or self-host it). It exposes window.AlpineComponent and auto-registers the plugin during alpine:init.

<!-- index.html -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/alpine-components@0.1.2/dist/alpine-components.min.js"></script>

<script>
document.addEventListener('alpine:init', () => {
  AlpineComponent.setBase('/components');
  AlpineComponent.register('modal', 'modal/modal.html', 'modal/modal.js');
});
</script>

3. Create a component

Components consist of an HTML template and an optional JS file for Alpine data:

src/components/
└── modal/
    ├── modal.html
    ├── modal.js
    └── modal.loading.html  ← optional

modal.html

<template>
<div x-data="modal">
    <button x-bind="trigger">Open Modal</button>
    <dialog x-bind="dialog">
        <article>
            <header>
                <slot name="header">
                    <p><strong>Modal Title</strong></p>
                </slot>
            </header>
            <slot name="body">
                <p>Modal content goes here.</p>
            </slot>
            <footer>
                <button x-bind="closeButton">Close</button>
            </footer>
        </article>
    </dialog>
</div>
</template>

modal.js

export default function modal() {
    return {
        isOpen: false,

        get trigger() {
            return { '@click'() { this.isOpen = true } };
        },

        get dialog() {
            return { 'x-bind:open'() { return this.isOpen } };
        },

        get closeButton() {
            return { '@click'() { this.isOpen = false } };
        }
    };
}

4. Use the component

<div x-component="modal"></div>

Live Demo

Loading...

Next Steps