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#https://railsdesigner.com/"
>
  Copy
</button>

<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-duration="5000"
>
  Copy
</button>

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

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

Use data-copy-duration="n" (in ms) to set the duration for the data-copy-success={true,false} to be added to the target element. This example has 5000 defined.

<button
  data-action="copy#`Spaceman, I always wanted you to go 🎶`"
>
  Copy
</button>

Use backticks to use spaces in your copyable value.

```
<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.

<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="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.

<div class="w-full h-48 border overflow-y-auto">
  <p
    data-action="intersect-once#opacity-100"
    class="mt-48 border-y p-4 opacity-0 transition-opacity duration-800 starting:opacity-0"
  >
    👻 “I was invisible, but now everyone can see me! Why did you scroll?”
  </p>
</div>

👻 “I was invisible, but now everyone can see me! Why did you scroll?”

Scroll the element to see opacity-100 added once it gets into the viewport. Transition via the starting class, e.g. starting:opacity-0.

<div class="relative w-full h-32 border overflow-y-auto bg-gradient-to-l from-cyan-400 to-sky-400">
  <div id="sticky" class="sticky top-0 left-0 w-full p-2 text-center border-b">
    Sticky element
  </div>

  <p
    data-action="intersect-toggle#bg-white/80,backdrop-blur-[3px]"
    data-target="#sticky"
    class="my-32 border-y p-4"
  >
    Just some text to view behind the sticky element.
  </p>
</div>

Sticky element

Just some text to view behind the sticky element.

Toggle the classes bg-white/80 and backdrop-blur-[3px] when the element is within the viewport.

```
<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.

<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 expects a data-target to be defined, otherwise it defaults to the current element, e.g. the element with the data-action attribute.

Example:

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

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.

<!-- Window events -->
<turbo-frame
  id="notifications"
  data-action="document@visibilitychange->reload"
>
</div>

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

<!-- Turbo events -->
<div
  data-action="document@turbo:load->removeClass#skeleton"
>
  Remove skeleton loader after page loads
</div>

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

Common global events include window@resize, window@scroll, document@turbo:load, and document@turbo:submit-end.

Nested `data-target` selector

You are not limited to a singular element when defining data-target. 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

Nested data-target selector

Set scope

Selectively enable available actions

Nested `data-target` selector