Attractive.js

Get started

Attractive.js works by defining a data-action and a data-target attribute (by default, the action applies to the element itself) to an element. The syntax for the data-action attribute is most commonly action#value. data-target accepts anything that can be passed to querySelectorAll(). Like this:

<p id="door">
  Paint me black.
</p>

<button data-action="toggleClass#bg-black" data-target="door">
  Paint it black
</button>

Upon clicking the button, the bg-black CSS class will be toggled (added, then removed) to the p#door element. There are a small dozen other actions, like addAttribute, copy and scrollTo. View all actions.

Installation

You can use Attractive.js either through a CDN, via NPM or importmap-rails.

Using a CDN

<head>
  <script defer src="https://cdn.jsdelivr.net/npm/attractivejs"></script>
</head>

And you are good to go! Optionally configure as needed:

<script>
  document.addEventListener("DOMContentLoaded", () => {
    // default usage (document as root)
    Attractive.activate();

    // selected element as root
    const element = document.querySelector("#main");
    Attractive.activate({ on: element });

    // only with selected actions
    Attractive.activate({ on: element }).withActions(["class", "attribute"]);
  });
</script>

Via NPM/importmap

npm install attractivejs

Using importmap-rails

./bin/importmap pin attractivejs

Then import Attractive into the apps' entrypoint (e.g. app/javascript/application.js):

import Attractive from "attractivejs";

Optionally configure as needed:

// default usage (document as root)
Attractive.activate();

// selected element as root
const element = document.getElementById("main");
Attractive.activate({ on: element });

// only with selected actions
Attractive.activate({ on: element }).withActions(["class", "attribute"]);

Actions

<button data-action="toggleAttribute#disabled=disabled" data-target="name">
  Toggle disabled State
</button>

<button data-action="addAttribute#disabled=disabled" data-target="name">
  Add disabled State
</button>

<button data-action="removeAttribute#disabled=disabled" data-target="name">
  Remove disabled State
</button>

<input type="text" id="name" class="name" placeholder="Can you focus on me?">

<button
  data-action="toggleAttribute#open"
  data-target="details"
>
  Toggle open
</button>

<details id="details">
  <summary>
    Want to see all the details?
  </summary>

  <p>These are some interesting details!</p>
</details>

Want to see all the details?

These are some interesting details!

<button
  data-action="cycleAttribute#type=password,text"
  data-target="password"
>
  View password
</button>

<input type="password" id="password" value="my secret" class="name">

<button
  data-action="addClass#bg-black"
  data-target="door-1"
>
  Paint it black
</button>

<p id="door-1">
  Paint me black.
</p>

Paint me black.

<button
  data-action="removeClass#bg-black"
  data-target="door-2"
>
  Remove black paint
</button>

<p id="door-2" class="bg-black">
  Paint me black.
</p>

Paint me black.

<button
  data-action="toggleClass#bg-black"
  data-target="door-3"
>
  Paint it back
</button>

<p id="door-3">
  Paint me black.
</p>

Paint me black.

<button
  data-action="toggleClass#bg-black,text-white"
  data-target="door-4"
>
  Paint it black with white
</button>

<p id="door-4">
  Paint me black.
</p>

Paint me black.

<button
  data-action="cycleClass#bg-black,bg-red-500"
  data-target="door-5"
>
  Paint it bled
</button>

<p id="door-5" class="bg-black">
  Paint me black.
</p>

Paint me black.

<button
  data-action="copy"
  data-target="share-link"
>
  Copy
</button>

<input type="text" id="share-link" value="https://railsdesigner.com/articles/" readonly="" class="[[data-copy-success='true']]:border-green-500">

A data-copy-success="true" attribute/value is added on the target element which is used to add a green border after copied.

<button
  data-action="copy"
  data-target="access-code"
  data-copy-delay="5000"
>
  Copy
</button>

<p>
Your access code is:
<code id="access-code" class="[[data-copy-success='true']]:text-green-500">ghi-789-jkl-012</code>
</p>

Your access code is: ghi-789-jkl-012

Use data-copy-delay="n" (in ms) to set the delay before the data-copy-success={true,false} gets removed from the target element. This example has 5000 defined.

```
<button
  id="failing-copy-button"
  data-action="copy#could-not-be-copied"
  class="[[data-copy-success='false']]:bg-red-100 [[data-copy-success='false']]:border-red-500"
>
  Copy
</button>
```
When copying to clipboard fails, the attribute data-copy-success="false" is added to the target.

<a href="https://railsdesigner.com" data-action="confirm" data-confirm-message="Really visit my website?">
  Visit my website
</a>

Visit my website

<input type="text" id="share-link" value="https://railsdesigner.com/articles/" readonly>
<button data-action="confirm copy" data-target="share-link">
  Copy URL to my website
</button>

Confirm an action by setting confirm first

<button
  data-action="addDataAttribute#tab=1"
  data-target="tabs"
>
  First tab
</button>

<button
  data-action="addDataAttribute#tab=2"
  data-target="#tabs"
>
  Second tab
</button>

<button
  data-action="addDataAttribute#tab=3"
  data-target="#tabs"
>
  Third tab
</button>

<ul id="tabs" data-tab="1">
  <li class="hidden [[data-tab='1']_&]:block">
    First tab content
  </li>

  <li class="hidden [[data-tab='2']_&]:block">
    Second tab content
  </li>

  <li class="hidden [[data-tab='3']_&]:block">
    Third tab content
  </li>
</ul>

First tab content
Second tab content
Third tab content

<button
  data-action="toggleDataAttribute#status=busy"
  data-target="bee-house"
>
  Toggle busy status
</button>

<div id="bee-house" class="relative p-4 border">
  Just some container that can be busy…

  <p class="hidden absolute inset-0 items-center justify-center text-white bg-black/30 backdrop-blur-sm [[data-status='busy']_&]:flex">
    It is busy! 🐝
  </p>
</div>

Just some container that can be busy…

<button
  data-action="cycleDataAttribute#light=stop,caution,go"
  data-target="traffic-light"
>
  Cycle traffic light
</button>

<ul id="traffic-light" class="relative flex flex-col">
  <li class="size-6 rounded-md bg-red-100 [[data-light='stop']_&]:bg-red-600"></li>

  <li class="size-6 rounded-md bg-orange-100 [[data-light='caution']_&]:bg-orange-400"></li>

  <li class="size-6 rounded-md bg-green-100 [[data-light='go']_&]:bg-green-600"></li>
</ul>

<button data-action="dialog#open" data-target="message">
  View dialog
</button>

<dialog id="message" class="m-auto p-2 border border-gray-200 rounded-md">
  <h2 class="text-lg font-bold">Feedback</h2>

  <p>Let me know what you think of Attractive.js 🤙</p>

  <form method="dialog" class="mt-2">
    <button type="button" data-action="dialog#close" data-target="message">Cancel</button>

    <button type="submit">Submit</button>
  </form>
</dialog>

<button data-action="dialog#openModal" data-target="with-backdrop">
  View dialog with backdrop
</button>

<dialog id="with-backdrop" closedby="any" class="p-2 m-auto">
  <h2 class="text-lg font-bold">Modal Heading</h2>
  <p>I got a message for you! Press Escape or click outside to close</p>
</dialog>

Use closedby="any" to allow close by clicking outside.

<button data-action="element#remove">
  Remove this button (click me)
</button>

<button data-action="element#remove" data-target="removable-item">
  Remove target element
</button>

<p id="removable-item" class="p-4 bg-gray-50">
  This element will be removed when the button is clicked.
</p>

This element will be removed when the button is clicked.

<button
  data-action="element#remove"
  data-target="delayed-item"
  data-remove-delay="2000"
>
  Remove after 2 seconds
</button>

<p id="delayed-item" class="p-4 bg-gray-50">
  This element will be removed 2 seconds after clicking the button.
</p>

This element will be removed 2 seconds after clicking the button.

Use data-remove-delay to specify after how many ms the element should be removed.

<button
  data-action="element#add"
  data-target="list-1"
  data-add-source="#item-template"
>
  Add item
</button>

<ul
  id="list-1"
  class="grid gap-2"
>
<li class="p-2 bg-gray-50">Existing item</li>
</ul>

<template id="item-template">
  <li class="p-2 bg-gray-50">New item</li>
</template>

Existing item

The added content is pulled from data-add-source. It can be a typical HTML element or a template. Use data-add-at='*' to specify where the added items need inserted. Valid options: beforeend (default), beforebegin, beforeend, afterend.

<button
  data-action="form#reset"
  data-target="reset-form"
>
  Reset form
</button>

<form id="reset-form" method="get" action="/#actions" class="p-2 border border-gray-100 rounded-sm">
  <label for="email">Email</label>
  <input type="email" placeholder="Enter something to see it reset again">

  <label for="name">Name</label>
  <input type="text" value="Rails Designer">
</form>

Allows to reset a form even when the button is outside of the form. Only fields without a value are reset.

<form id="preferences" method="get" action="/#actions" class="p-2 border border-gray-100 rounded-sm">
  <label for="framework">Framework (submits form on select)</label>

  <select
    id="framework"
    name="framework"
    data-action="form#submit"
    data-target="preferences"
  >
    <option value="">Choose your JS library</option>
    <option value="attractive">attractive.js</option>
    <option value="turbo">turbo</option>
    <option value="stimulus">stimulus</option>
  </select>
</form>

This add ?framework=* to the url since the form has method=get.

<form id="more-preferences" method="get" action="/#actions" class="p-2 border border-gray-100 rounded-sm">
  <label for="framework">Framework (submits form on select)</label>

  <select
    id="framework"
    name="framework"
    data-action="form#submit"
    data-target="more-preferences"
    data-submit-delay="2000"
  >
    <option value="">Choose your JS library</option>
    <option value="attractive">attractive.js</option>
    <option value="turbo">turbo</option>
    <option value="stimulus">stimulus</option>
  </select>
</form>

Use data-submit-delay="n" (where n is in ms) to add a debounce/delay before submit. This example uses 2000ms.

```
<button
  data-action="reload"
  data-target="turbo-frame"
>
  Reload
</button>

<turbo-frame></turbo-frame>
```
```
<button data-action="reload">
  Reload
</button>
```
With no data-target the page is refreshed. Note: reload is aliased to refresh.

<button
  type="button"
  data-action="get#/"
  data-target="content"
>
  Load this homepage below
</button>

<div id="content" class="max-h-96 overflow-scroll">
  <span class="hidden [[data-request-busy='true']_&]:block">Loading…</span>
</div>

When loading data-request-busy="true" is added, and upon success data-request-success="true" is added, to the target.

```
<select name="theme" id="theme" data-action="patch#/preferences">
  <option value="dark">Dark</option>
  <option value="light">Light</option>
</select>
```

<ul class="w-full h-32 overflow-y-auto border">
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
  <li>Item 4</li>
  <li>Item 5</li>
  <li>Item 6</li>
  <li>Item 7</li>
  <li>Item 8</li>
  <li>Item 9</li>
  <li>Item 10</li>
  <li>Item 11</li>
  <li>Item 12</li>
  <li>Item 13</li>
  <li>Item 14</li>
  <li data-action="scrollTo#smooth" class="bg-amber-100">Item 15 (target)</li>
  <li>Item 16</li>
  <li>Item 17</li>
  <li>Item 18</li>
  <li>Item 19</li>
  <li>Item 20</li>
</ul>

Item 1
Item 2
Item 3
Item 4
Item 5
Item 6
Item 7
Item 8
Item 9
Item 10
Item 11
Item 12
Item 13
Item 14
Item 15 (target)
Item 16
Item 17
Item 18
Item 19
Item 20

Other valid options are instant and auto (which will inherit the value defined in CSS)

Reference

Quick reference of various Attractive.js features.

Implicit target

Attractive.js assumes a data-target to be defined; if not provided, it defaults to the current element, i.e. the element with the data-action attribute.

Example:

<button data-action="addClass#clicked">
  Add `clicked` class to the button
</button>

Comma separated values

Some actions support multiple values by separating them with a comma, e.g. data-action="toggleClass=bg-black,text-white". These actions support multiple values:

addClass
removeClass
toggleClass
cycleClass
cycleAttribute
cycleDataAttribute

Events

Actions run using default event listeners based on HTML element types. Attractive.js automatically assigns appropriate events.

Element	Default event
`<a>`, `<button>`	`click`
`<input type="text">`	`input`
`<input type="checkbox">`, `<input type="radio">`	`change`
`<input type="submit">`, `<input type="button">`	`click`
`<select>`	`change`
`<textarea>`	`input`
`<form>`	`submit`
Other elements	`click`

Custom events

Specify custom events using the arrow syntax: event->action.

<input
  type="text"
  data-action="keyup->removeClass#hidden"
  data-target="clear-button"
>

Global events

Listen to window and document events using window@ or document@ prefixes.

<!-- Auto-dismiss flash messages -->
<ul id="flash">
  <li data-action="document@DOMContentLoaded->element#remove" data-remove-delay="5000">
    Profile updated successfully
  </li>
</ul>

<!-- Network status indicator -->
<span
  data-action="window@online->removeClass#offline window@offline->addClass#offline"
  class="status-indicator"
>
</span>

<!-- Turbo navigation loading state -->
<body
  data-action="document@turbo:before-visit->addClass#loading document@turbo:load->removeClass#loading"
>
</body>

Common events: window@resize, window@scroll, window@online, window@offline, document@DOMContentLoaded, document@turbo:load, document@turbo:before-visit.

Modifiers

Use modifiers, using the colon syntax, to control when actions execute. There are two available modifiers:

:mounted (“aliased” to now): when element is (programmatically) added to the DOM;
:whenVisible: when element enters viewport.

Example: <li data-action="element#remove:mounted" data-remove-delay="6000">Profile updated</li>.

Nested `data-targets` selector

You are not limited to a singular element when defining data-targets. A nested selector, like #form [type=checkbox] would work as well and would query all checkbox elements within the #form selector.

Set scope

Attractive.js is by default enabled to the whole document. You can activate it to a certain element only if needed. For example only on the #main element.

Attractive.activate();

const main = document.querySelector("#main");
Attractive.activate({ on: main });

Selectively enable available actions

You can enable or disable any Attractive.js action when initializing. For example only enable the class and attribute actions.

Attractive.activate();

Attractive.activate({ on: element }).withActions(["class", "attribute"]);

by Rails Designer • View Attractive.js on GitHub

A JavaScript-free JavaScript library

Get started

Installation

Using a CDN

Via NPM/importmap

Actions

Reference

Implicit target

Comma separated values

Events

Custom events

Global events

Modifiers

Nested data-targets selector

Set scope

Selectively enable available actions

Nested `data-targets` selector