API Reference

Plugin Initialization

The library is an Alpine.js plugin that adds component management capabilities.

`components(options?)`

Initialize the plugin with optional configuration.

Option	Type	Description
`base`	`string \| [string, string]`	Base path for components. Can be a single string or a tuple for `[htmlBase, jsBase]`.
`alias`	`string \| [string, string]`	Pattern for resolving component names to paths using `[name]` and `[ext]` placeholders.

// Standard usage
Alpine.plugin(components({
  base: '/assets/components/',
  alias: '[name]/[name].[ext]'
}));

Alpine.components

The core object for managing component registration.

`Alpine.components.register(name, templatePath, jsPath?)`

Parameter	Type	Description
`name`	`string`	Component name used in `x-component="name"`
`templatePath`	`string \| object`	Path to HTML template, or an options object.
`jsPath`	`string?`	Optional path to JS module exporting Alpine data function.

// Simple registration
Alpine.components.register('modal', 'modal.html', 'modal.js');

// Object syntax with eager loading
Alpine.components.register('header', {
  template: 'header.html',
  js: 'header.js',
  eager: true
});

x-component Directive

The Alpine directive for rendering components.

Usage Varieties

Syntax	Description
`x-component="name"`	Resolves via registry or alias pattern.
`x-component="path.html"`	Loads HTML directly from path (no JS).
`x-component="['h.html', 'j.js']"`	Loads both HTML and JS from explicit paths.

Element Types

While x-component works on any element, using it on a <template> tag is preferred as it avoids "layout shift" by replacing itself with the component content.

<template x-component="modal" title="Welcome">
    <p>Body content</p>
</template>

Modifiers (Strategies)

Modifier	Description	Example
`.eager`	Load immediately (default).	`x-component.eager="modal"`
`.visible`	Load when element enters viewport.	`x-component.visible="modal"`
`.event`	Load on custom event or `alpine-components:load`.	`x-component.event.my-event="modal"`

$params Magic

Access attributes passed to the component from the caller.

<!-- Caller -->
<template x-component="user-profile" user-id="123" :active="true"></template>

<!-- Component (user-profile.html) -->
<div x-data="profile($params.userId)">
    <p x-show="$params.active">User ID: <span x-text="$params.userId"></span></p>
</div>

Note: Attributes are automatically converted from kebab-case to camelCase when accessed via $params.