@ramstack/alpinegear-when

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

This directive is used for conditionally rendering elements on the page, similar to x-if.

However, unlike x-if, it supports multiple root elements inside the <template> tag. Essentially, x-when works like a combination of x-if and x-fragment, but with cleaner syntax. There's no need to nest multiple <template> tags, which makes the markup simpler and easier to manage.

[!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-when@1/alpinegear-when.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-when

Then initialize it in your bundle:

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

Alpine.plugin(when);
Alpine.start();

Usage

The x-when directive functions similarly to x-if, but allows multiple root elements in the <template> tag:

<div x-data="{ show: false }">
  <button @click="show = !show">Show more</button>

  <ul>
    <li>Apple</li>
    <li>Banana</li>

    <template x-when="show">
      <li>Orange</li>
      <li>Grape</li>
      <li>Mango</li>
    </template>
  </ul>
</div>

🚀 Live demo | Alpine.js x-when: Multiple root elements

Using with x-for

The x-when directive can also be used with the directive x-for to conditionally render multiple items:

<div x-data="{
  items: [
    { term: 'Star', description: 'Luminous plasma sphere.' },
    { term: 'Planet', description: 'Body orbiting a star.' },
    { term: 'Galaxy', description: 'Stars and dust system.' },
    { term: 'Nebula', description: 'Cloud of gas in space.' }
  ]}">
  <button @click="items.reverse()">Reverse</button>

  <dl>
    <template x-for="item in items" :key="item.term">
      <template x-when="true">
        <dt x-text="item.term"></dt>
        <dd x-text="item.description"></dd>
      </template>
    </template>
  </dl>
</div>

🚀 Live demo | Alpine.js x-when: Multiple root elements with x-for

Source code

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

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

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.