Abstract:

This document is a comprehensive technical reference for the HTML data-* attributes of the Datastar framework, a library designed for building reactive web interfaces by embedding logic directly into the DOM. It details a wide range of attributes for managing application state through "signals," a core reactive primitive. Key functionalities covered include two-way data binding (data-bind), dynamic attribute and class manipulation (data-attr, data-class), conditional element visibility (data-show), and event handling (data-on) with advanced modifiers for debouncing and throttling. The guide also explains attributes for managing derived state (data-computed) and side effects (data-effect). The documentation distinguishes between standard attributes and "Pro" attributes, available under a commercial license, which add advanced capabilities like state persistence (data-persist), URL synchronization (data-query-string), and animations. Foundational concepts such as attribute processing order, casing conventions, and built-in error handling are also outlined.

Datastar Framework: A Guide to its Core Reactive Attributes

• data-signals: This is the fundamental attribute for declaring and initializing the application's state, known as "signals." Signals are reactive, meaning any changes to their values will automatically update the parts of the UI that depend on them.
• data-bind: Creates a two-way data binding between a form element (like an input or select box) and a signal. This means changes in the UI update the signal, and changes to the signal's value update the UI. It intelligently preserves the data type (e.g., number, array) of a predefined signal.
• data-show & data-class: These attributes provide simple, declarative control over an element's appearance based on state. data-show toggles an element's visibility, while data-class conditionally adds or removes CSS classes, allowing for dynamic styling.
• data-computed & data-effect: These attributes manage derived state and side effects. data-computed creates a new, read-only signal whose value is calculated from other signals, providing a performance-optimized (memoized) value. data-effect executes a function whenever its dependent signals change, ideal for triggering actions like API calls.
• data-on: A powerful event listener that executes an expression when a DOM event occurs (e.g., data-on-click). It is highly customizable with modifiers to debounce, throttle, delay, or run an event listener only once.
• data-indicator: Simplifies loading state management for asynchronous operations. It creates a boolean signal that is automatically true while a fetch request is in flight and false when it completes, making it easy to show loading spinners or disable buttons.
• data-on-load & data-on-intersect: These attributes act as lifecycle hooks for elements. data-on-load runs an expression when an element is first added to the DOM, and data-on-intersect triggers when an element scrolls into the viewport, useful for lazy-loading images or animations.
• data-ignore: Provides an escape hatch to prevent Datastar from processing an element and its children. This is crucial for integrating with third-party libraries or preventing conflicts with user-generated content.
• Pro Attributes (data-persist, data-query-string): The commercial version adds powerful capabilities. data-persist automatically saves specified signals to local or session storage between page loads, while data-query-string syncs signal values with the URL's query parameters, enabling shareable and bookmarkable application states.
• Attribute Modifiers: A core concept used across the framework. Suffixes like __once, __debounce, __delay, and __case are added to attributes to provide fine-grained control over their behavior, such as timing, casing, and execution conditions.