@ramstack/alpinegear-format

@ramstack/alpinegear-format is a plugin for Alpine.js that provides the x-format directive.

This directive allows you to easily interpolate text using a template syntax similar to what's available in Vue.js.

[!Note] This package is part of the @ramstack/alpinegear-main bundle. If you are using the main bundle, you don't need to install this package separately.

Installation

Using CDN

To include the CDN version of this plugin, add the following <script> tag before the core alpine.js file:

<!-- alpine.js plugin -->
<script src="https://cdn.jsdelivr.net/npm/@ramstack/alpinegear-format@1/alpinegear-format.min.js" defer></script>

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

Using NPM

Alternatively, you can install the plugin via npm:

npm install --save @ramstack/alpinegear-format

Then initialize it in your bundle:

import Alpine from "alpinejs";
import format from "@ramstack/alpinegear-format";

Alpine.plugin(format);
Alpine.start();

Usage

The x-format directive enables you to use double curly braces ({{ ... }}) to evaluate expressions and inject their values into the DOM. The expressions within placeholders can be any valid script expression, such as variables, arithmetic operations, or function calls, as long as they are available in the Alpine.js scope.

<div x-data="{ message: 'Hello, World!' }" x-format>
  <input x-model="message" />

  <p>
    Message: {{ message || "Empty" }}
  </p>
</div>

🚀 Live demo | Alpine.js x-format: Interpolate expression

In this example, {{ message || "Empty" }} will be replaced by the evaluated result, and the content will update whenever the message property change.

Using with Attributes

The x-format directive can also be used to interpolate values inside HTML attributes:

<div x-data="{ message: 'Hello, World!' }" x-format>
  <input x-model="message" />

  <p title="Message: {{ message }}">
    Message: {{ message }}
  </p>
</div>

🚀 Live demo | Alpine.js x-format: Interpolate expression

Just like with text interpolation, the attribute values will be updated automatically when the data changes.

[!IMPORTANT] The x-format directive treats evaluated expressions as plain text, not HTML, ensuring safe rendering and preventing injection attacks like XSS.

If you need to render HTML, use the x-html directive instead.

[!WARNING] Keep in mind that interpolation within a <textarea> element may not work as you expect.

Use x-model instead.

Using once modifier

The once modifier allows you to interpolate the expression only once. After the initial rendering, the content remains static and will not update, even if the data changes.

<div x-data="{ message: 'Hello, World!'}" x-format.once>
  <input x-model="message" />
  <p>
    {{ message }}
  </p>
</div>

🚀 Live demo | Alpine.js x-format: Interpolate expression only once

Optimization

The x-format directive is optimized to update only the parts of the text that change, without replacing the entire DOM element. This is especially useful for large or complex DOM structures.

For example:

<div x-data="{ message: 'Hello, World!'}" x-format>
  The 'message' value is '{{ message }}' and it updates when the property changes.
</div>

In this case, the text will be split into three separate text nodes:

1. The 'message' value is '
2. {{ message }}
3. ' and it updates when the property changes.

Only the {{ message }} text node will be updated, while the static nodes will remain unchanged.

[!NOTE] This optimization does not apply to attribute values.

Dynamic Elements

Since the x-format directive doesn't automatically track changes to the DOM, newly added elements (e.g., via x-if or x-for) will not automatically interpolate their templates.

For instance, in the example below, the {{ message }} inside x-if remains unchanged:

<div x-data="{ show: false, message: 'Hello, World!'}" x-format>
  <template x-if="show">
    <p>{{ message }}</p>
  </template>
</div>

To ensure proper interpolation, include the x-format directive in the dynamically rendered elements:

<div x-data="{ show: false, message: 'Hello, World!' }">
  <input x-model="message" />

  <label>
    <input type="checkbox" x-model="show" />
    Show message
  </label>

  <template x-if="show">
    <p x-format>{{ message }}</p>
  </template>
</div>

🚀 Live demo | Alpine.js x-format: Dynamic elements

Source Code

You can find the source code for this plugin on GitHub:

https://github.com/rameel/ramstack.alpinegear.js/tree/main/src/plugins/format

Related packages

This package is part of AlpineGear — a collection of utilities and directives for Alpine.js.

You can find the full list of related packages and their documentation here: https://github.com/rameel/ramstack.alpinegear.js

Contributions

Bug reports and contributions are welcome.

License

This package is released as open source under the MIT License. See the LICENSE file for more details.