6.6 KiB
Datastar API Reference
Attribute Plugins
Attribute plugins are data-* attributes that add reactive behavior to HTML elements.
Core Plugins
| Plugin | Description |
|---|---|
data-signals |
Merges one or more signals into the existing signals. |
data-computed |
Creates a read-only signal computed from an expression. |
data-ref |
Creates a signal reference to the DOM element. |
data-star-ignore |
Ignores an element and its descendants when processing. |
DOM Plugins
| Plugin | Description |
|---|---|
data-attr |
Sets any HTML attribute value using expressions. |
data-bind |
Creates two-way data binding between a signal and an element's value. |
data-class |
Adds or removes CSS classes based on expressions. |
data-on |
Attaches event listeners that execute expressions. |
data-persist |
Persists signals in Local Storage or Session Storage. |
data-replace-url |
Replaces the URL in the browser without page reload. |
data-text |
Binds text content of an element to an expression. |
Browser Plugins
| Plugin | Description |
|---|---|
data-custom-validity |
Adds custom validation to elements. |
data-intersects |
Runs expressions when elements intersect the viewport. |
data-scroll-into-view |
Scrolls elements into view with various options. |
data-show |
Shows or hides elements based on expressions. |
data-view-transition |
Sets view-transition-name for View Transitions API. |
Backend Plugins
| Plugin | Description |
|---|---|
data-indicator |
Creates signals that indicate when SSE requests are in flight. |
View the attribute plugins reference.
Action Plugins
Action plugins are used in Datastar expressions to perform specific actions.
| Plugin | Description |
|---|---|
@get() |
Sends a GET request to the backend and merges the response. |
@post() |
Sends a POST request to the backend and merges the response. |
@put() |
Sends a PUT request to the backend and merges the response. |
@patch() |
Sends a PATCH request to the backend and merges the response. |
@delete() |
Sends a DELETE request to the backend and merges the response. |
@clipboard() |
Copies the provided evaluated expression to the clipboard. |
@setAll() |
Sets all signals with a specific prefix to a provided value. |
@toggleAll() |
Toggles all signals that start with a given prefix. |
@fit() |
Makes a value linearly interpolate from an original range to a new one. |
View the action plugins reference.
Expression Context
Datastar expressions have access to a context object (ctx) providing:
- Current element reference (
ctx.el) - Signals root object for accessing and modifying signals (
ctx.signals)
View the expression context reference
Server-Sent Events
Datastar uses Server-Sent Events (SSE) to communicate from the server to the client.
| Event Type | Description |
|---|---|
datastar-merge-fragments |
Merges HTML fragments into the DOM with various merge strategies. |
datastar-merge-signals |
Updates signals with new values. |
datastar-remove-fragments |
Removes HTML fragments matching selectors. |
datastar-remove-signals |
Removes signals matching specific paths. |
datastar-execute-script |
Executes JavaScript in the browser. |
View the SSE events reference.
SDKs
Officially supported SDKs for generating Datastar-specific SSE events:
- Clojure
- dotnet
- Go
- Haskell
- Java
- PHP (with Laravel and Craft CMS packages)
- Python
- Rust
- Ruby
- TypeScript
- Zig
View the SDK reference.
Security
Security guidelines for using Datastar expressions safely:
| Consideration | Description |
|---|---|
| Escape User Input | Always escape user input to prevent XSS attacks when using Datastar expressions. |
| Avoid Sensitive Data | Signal values are visible in source code and can be modified, avoid using sensitive data. |
| data-star-ignore | Use this attribute to ignore unsafe content that cannot be escaped. |
| Content Security Policy | Requires 'unsafe-eval' for script sources since Datastar evaluates expressions using IIFE. |
View the security reference.
Custom Builds
Datastar is built using a modular architecture that allows you to create custom builds with only the plugins you need, useful for reducing the framework's footprint.
Key features:
- Use the bundler web interface to select only needed plugins
- Create aliased builds (data-ds-*) to resolve conflicts with legacy libraries
- Use the NPM package to create custom builds programmatically
View the custom builds reference.