- Backend-Driven UI: The backend is the primary source of truth. It drives frontend state and logic by sending HTML patches, signal updates, or executable scripts to the client.
- Hypermedia Approach: User actions trigger requests to the backend, which responds with changes to the UI, effectively determining the next set of possible user interactions.
- Declarative Attributes: Use data-* attributes in HTML to handle all frontend reactivity, event handling, and communication with the backend.
- Patching Elements: The backend updates the DOM by sending HTML. Datastar uses a morphing strategy, matching element IDs to update only what has changed.
- Trigger: A frontend action like <button data-on-click="@get('/update-ui')">.
- Response: The backend sends a text/html response. The top-level elements in the response must have IDs that match existing elements in the DOM.
- SSE Event: event: datastar-patch-elements
- Patching Signals: The backend updates frontend reactive state (signals) directly.
- Trigger: A frontend action like <button data-on-click="@get('/update-state')">.
- Response: The backend sends an application/json response.
- SSE Event: event: datastar-patch-signals
- Executing Scripts: The backend can send JavaScript for the browser to execute.
- Trigger: A frontend action like <button data-on-click="@get('/run-script')">.
- Response: The backend sends a text/javascript response.
- SSE Method: Use the ExecuteScript() SDK helper or a datastar-patch-elements event containing a <script> tag.
- Signals: Reactive variables that manage frontend state. They are always prefixed with a $ (e.g., $foo).
- Initialization: Define signals with data-signals="{foo: 'initial value', form: {name: ''}}". Signals can be nested.
- Two-Way Binding: Use data-bind on input elements for two-way data binding.
- Example: <input data-bind-foo /> or <input data-bind="foo.name" /> creates and binds the $foo or $foo.name signal.
- Displaying Data: Use data-text to set an element's text content to the value of an expression.
- Example: <span data-text="$foo.toUpperCase()"></span>
- Conditional Rendering/Attributes:
- data-show="$foo != ''": Shows/hides an element.
- data-class-active="$foo == 'bar'": Toggles a single class.
- data-class="{active: $foo, disabled: !$bar}": Toggles multiple classes.
- data-attr-disabled="$foo == ''": Sets an attribute based on an expression.
- Computed Signals: Create a new, read-only signal derived from other signals using data-computed.
- Example: <div data-computed-isValid="$name.length > 3" data-show="$isValid"></div>
- Event Handling: Use data-on to execute expressions on DOM events.
- Example: <button data-on-click="$counter = $counter + 1; $name = ''">Click Me</button>
Datastar's data-* attributes are the core of its frontend functionality. They are evaluated in the order they appear in the DOM, have specific casing rules, and can be aliased to prevent conflicts. They support Datastar expressions and have built-in runtime error handling.
- data-attr: Sets one or more HTML attributes based on an expression.
- <div data-attr-title="$foo"></div>
- <div data-attr="{title: $foo, disabled: $bar}"></div>
- data-bind: Creates a signal and establishes two-way data binding with an element's value.
- <input data-bind-foo value="bar" />
- Preserves the type of predefined signals (e.g., number, array).
- data-class: Adds or removes one or more CSS classes based on an expression.
- <div data-class-hidden="$foo"></div>
- <div data-class="{hidden: $foo, 'font-bold': $bar}"></div>
- data-computed: Creates a read-only signal that is derived from other signals.
- <div data-computed-foo="$bar + $baz"></div>
- data-effect: Executes an expression on page load and whenever any of its dependent signals change. Useful for side effects.
- <div data-effect="$foo = $bar + $baz"></div>
- data-ignore: Prevents Datastar from processing an element and its descendants.
- data-ignore-morph specifically prevents morphing of an element.
- data-indicator: Creates a boolean signal that is true while a fetch request is in flight.
- <button data-on-click="@get('/endpoint')" data-indicator-fetching></button>
- data-on: Attaches an event listener to an element to execute an expression. Supports numerous modifiers for debouncing, throttling, and more.
- <button data-on-click__debounce.500ms="$foo = ''"></button>
- data-on-intersect: Executes an expression when an element intersects with the viewport.
- data-on-interval: Executes an expression at a regular interval.
- data-on-load: Executes an expression when the element is loaded into the DOM.
- data-ref: Creates a signal that is a reference to the DOM element.
- data-show: Shows or hides an element based on an expression.
- data-signals: Initializes or updates one or more signals.
- <div data-signals-foo="1"></div>
- <div data-signals="{foo: {bar: 1}}"></div>
- data-style: Sets one or more inline CSS styles based on an expression.
- data-text: Sets the text content of an element based on an expression.
- data-animate: Animates element attributes over time.
- data-custom-validity: Adds custom validation to form elements.
- data-persist: Persists signals in local or session storage.
- data-query-string: Syncs signals with URL query string parameters.
- data-replace-url: Replaces the browser's URL without a page reload.
- data-scroll-into-view: Scrolls an element into view.
- data-view-transition: Explicitly sets the view-transition-name for an element.
Actions are secure functions that can be used within Datastar expressions, prefixed with @.
- @peek(): Accesses a signal's value without creating a reactive dependency.
- @setAll(): Sets the value of all signals that match a filter.
- @toggleAll(): Toggles the boolean value of all signals that match a filter.
These actions send requests to the backend using the Fetch API. By default, they send all signals with the request.
- @get(uri, options)
- @post(uri, options)
- @put(uri, options)
- @patch(uri, options)
- @delete(uri, options)
Response Handling: Backend actions automatically handle different Content-Type responses:
- text/event-stream: Server-Sent Events (SSE).
- text/html: HTML to be patched into the DOM.
- application/json: JSON data to patch signals.
- text/javascript: JavaScript to be executed.
Upload Progress (Pro): All backend actions support file upload progress monitoring with multipart/form-data over HTTPS.
- @clipboard(): Copies text to the clipboard.
- @fit(): Linearly interpolates a value from one range to another.