AlpineJS Skill: Custom Directives with Alpine.directive()

alpine:init Event:

This JavaScript event fires after Alpine.js has initialized itself but before it processes any components on the page (i.e., before it scans for x-data, x-init, etc.). It is the recommended place to register custom directives, global stores (Alpine.store()), and define global component data factories (Alpine.data()) that need to be available universally.

document.addEventListener('alpine:init', () => {
    // Register custom directives here
    Alpine.directive(...);

    // Define global stores
    Alpine.store(...);

    // Define global component data
    Alpine.data(...);
});

Alpine.directive('name', (el, { expression, modifiers, originalExpression }, { Alpine, effect, cleanup, evaluate, evaluateLater }) => { ... }):

This is the core function for defining a custom directive. Let's break down its arguments:

• 'name' (string): The name of your directive. If you pass 'foo', you'll use it in HTML as x-foo.

• el (HTMLElement): The DOM element the directive is attached to.

• Directive Bag { expression, modifiers, originalExpression } (object):

  • expression (string): The JavaScript expression provided to the directive in the HTML (e.g., for x-foo="bar()", expression would be "bar()").
  • modifiers (Array<string>): An array of "modifiers" appended to the directive name (e.g., for x-foo.first.second, modifiers would be ['first', 'second']).
  • originalExpression (string): The raw, unparsed expression string from the attribute.

• Utilities Bag { Alpine, effect, cleanup, evaluate, evaluateLater } (object):

  • Alpine: The global Alpine object, useful for accessing other Alpine internals if needed.
  • effect(() => { ... }): A powerful utility. It runs the provided callback immediately and then re-runs it automatically whenever any reactive Alpine data used inside the callback changes. This is crucial for directives that need to react to state changes.
  • cleanup(() => { ... }): Registers a callback function that will be executed when the element is removed from the DOM or when the directive is "cleaned up" by Alpine (e.g., if the element is part of an x-for loop and an item is removed). Use this to remove event listeners, clear timers, or release any resources your directive might have set up.
  • evaluate(expressionString): Executes a JavaScript expression string within the context of the current Alpine component (i.e., it has access to the component's data and methods). It returns the result of the expression.
  • evaluateLater(expressionString): Similar to evaluate, but instead of executing immediately, it returns a function. When this returned function is called, it then executes the expression. This is useful for event handlers or situations where you need to delay evaluation.

Example Signature:

Alpine.directive('my-directive', (el, { expression, modifiers }, { effect, cleanup, evaluate }) => {
    // 'el' is the HTML element
    // 'expression' is the value of x-my-directive=""
    // 'modifiers' is an array of strings like ['mod1', 'mod2'] for x-my-directive.mod1.mod2

    if (modifiers.includes('highlight')) {
        el.style.backgroundColor = 'yellow';
    }

    let value = evaluate(expression); // Evaluate the expression
    console.log('Directive value:', value);

    effect(() => {
        // This will re-run if 'someReactiveProperty' in the expression changes
        let currentValue = evaluate(expression);
        el.textContent = \`Current reactive value: \${currentValue}\`;
    });

    cleanup(() => {
        // Perform cleanup, e.g., remove event listeners
        console.log('Cleaning up my-directive from', el);
    });
});