Datastar

https://data-star.dev
Admin
Datastar is a lightweight hypermedia framework for building reactive, real-time web applications by...
Tokens:149,052
Snippets:1,081
Trust Score:8.2
Update:1 week ago
Show doc for...
Tokens:
Raw
### setup hook example: demo-timer

Source: https://data-star.dev/reference/rocket

Example of using setup to manage a timer that increments a local signal based on props. It uses observeProps to react to prop changes and cleanup to clear the timer on teardown. The render function displays the seconds value.

```javascript
rocket('demo-timer', {
  props: ({ number, bool }) => ({
    intervalMs: number.min(50).default(1000),
    autoplay: bool,
  }),
  setup: ({ $$, cleanup, props, observeProps }) => {
    $$.seconds = 0
    let timerId = 0

    let syncTimer = () => {
      clearInterval(timerId)
      if (!props.autoplay) {
        return
      }
      timerId = window.setInterval(() => {
        $$.seconds += 1
      }, props.intervalMs)
    }

    syncTimer()
    observeProps(syncTimer)

    cleanup(() => clearInterval(timerId))
  },
  render: ({ html }) => {
    return html`
        <p data-text="$$seconds"></p>
    `
  },
})
```

--------------------------------

### Basic CQRS example with Datastar attributes

Source: https://data-star.dev/guide/the_tao_of_datastar

Shows a basic CQRS setup where a long-lived request receives updates from the backend via data-init, and short-lived write requests are made via data-on:click. The div has an id of 'main' and uses the @get and @post actions.

```html
<div id="main" data-init="@get('/cqrs_endpoint')">
    <button data-on:click="@post('/do_something')">
        Do something
    </button>
</div>
```

--------------------------------

### rocket('demo-copy-button', { props, setup, render })

Source: https://data-star.dev/reference/rocket

Example of defining a Rocket web component with props, setup, and render functions. Demonstrates local state, actions, cleanup, and rendering.

```APIDOC
## rocket('demo-copy-button', { props, setup, render })

### Description
Defines a Rocket web component named 'demo-copy-button' with props, setup logic, and a render function. The setup function uses local state, global signals, actions, and cleanup.

### Method
rocket()

### Parameters
#### Component Definition Object
- **props** (object) - Required - Defines the component's props with types and defaults.
- **setup** (function) - Required - Runs once per instance, receives setup context helpers.
- **render** (function) - Required - Returns the component's HTML template.

### Setup Context Helpers
- **props** - The normalized prop values for the current instance.
- **$$** - Creates mutable instance-local state and exposes it on `$$.name`.
- **effect(fn)** - Runs a reactive side effect and tracks cleanup.
- **apply(root, merge?)** - Runs Datastar apply on a root.
- **cleanup(fn)** - Registers disconnect cleanup.
- **$** - Reads and writes the global Datastar signal store.
- **actions** - Calls Datastar global actions from setup code.
- **action(name, fn)** - Registers a local action callable from rendered markup.
- **observeProps(fn, ...propNames)** - Responds to prop changes after decoding.
- **overrideProp(name, getter?, setter?)** - Wraps a declared prop's default host accessor for this instance.
- **defineHostProp(name, descriptor)** - Defines a host-only property or method on this instance.
- **render(overrides, ...args)** - Reruns the component render function from setup code.
- **host** - The current custom element instance.

### Example
```js
rocket('demo-copy-button', {
  props: ({ string, number }) => ({
    text: string.default('Copy me'),
    resetMs: number.min(100).default(1200),
  }),
  setup: ({ $$, $, action, actions, cleanup, props }) => {
    $$.copied = false
    $$.label = () => ($$.copied ? 'Copied' : 'Copy')
    $$.resetMsLabel = actions.intl(
      'number',
      props.resetMs,
      { maximumFractionDigits: 0 },
      'en-US',
    )
    let timerId = 0

    action('copy', async () => {
      await navigator.clipboard.writeText(props.text)
      $$.copied = true
      if ($.analyticsEnabled !== false) {
        $.lastCopiedText = props.text
      }
      clearTimeout(timerId)
      timerId = window.setTimeout(() => {
        $$.copied = false
      }, props.resetMs)
    })

    cleanup(() => clearTimeout(timerId))
  },
  render: ({ html, props: { text } }) => {
    return html`
      <button data-on:click="@copy()">
        <span data-text="$$label"></span>
        <small>${text} ($$resetMsLabel ms)</small>
      </button>
    `
  },
})
```

### Notes
- Local actions are optional; prefer plain Datastar expressions for simple state changes.
- The name `dispatchRocket` is reserved for Rocket's internal action dispatcher.
- `$$` is the setup alias for Rocket-local signals; assigning a function creates a computed signal.
- `actions` exposes the global Datastar action registry.
- `$` exposes the shared Datastar signal root.
- Local refs created with `data-ref:name` are exposed on `onFirstRender({ refs })` as `refs.name`.
```

--------------------------------

### Rocket render example: counter component

Source: https://data-star.dev/reference/rocket

Defines a light-mode custom element 'demo-stepper' with typed props (start, step, label), local state via setup, and a render function using Datastar attributes for event handling and bindings. The render output uses the html tagged template and reads/writes local signals.

```javascript
rocket('demo-stepper', {
  mode: 'light',
  props: ({ number, string }) => ({
    start: number.min(0),
    step: number.min(1).default(1),
    label: string.trim.default('Count'),
  }),
  setup: ({ $$, props }) => {
    $$.count = props.start
  },
  render: ({ html, props: { label, step } }) => {
    return html`
      <section class="stack gap-2">
        <h3>${label}</h3>
        <div class="row gap-2">
          <button data-on:click="$$count -= ${step}" data-attr:disabled="$$count <= 0">-</button>
          <output data-text="$$count"></output>
          <button data-on:click="$$count += ${step}">+</button>
        </div>
      </section>
    `
  },
})
```

--------------------------------

### setup

Source: https://data-star.dev/reference/rocket

The setup hook runs once per connected element instance after Rocket creates the component scope and before the initial Datastar apply pass. Use it for local signals, computed state, prop observers, timers, cleanup handlers, and host APIs that do not depend on rendered refs.

```APIDOC
## setup

### Description
The `setup` hook runs once per connected element instance after Rocket creates the component scope and before the initial Datastar apply pass. It is the default place for local signals, computed state, prop observers, timers, cleanup handlers, and host APIs that do not depend on rendered refs.

### Signature
`setup?: (context: SetupContext<InferProps<Defs>>) => void`

### Parameters
- `context` (SetupContext<InferProps<Defs>>) - Required - The setup context, providing access to `$$`, `cleanup`, `props`, `observeProps`, `render`, and other helpers.

### Example
```js
rocket('demo-timer', {
  props: ({ number, bool }) => ({
    intervalMs: number.min(50).default(1000),
    autoplay: bool,
  }),
  setup: ({ $$, cleanup, props, observeProps }) => {
    $$.seconds = 0
    let timerId = 0

    let syncTimer = () => {
      clearInterval(timerId)
      if (!props.autoplay) {
        return
      }
      timerId = window.setInterval(() => {
        $$.seconds += 1
      }, props.intervalMs)
    }

    syncTimer()
    observeProps(syncTimer)

    cleanup(() => clearInterval(timerId))
  },
  render: ({ html }) => {
    return html`
        <p data-text="$$seconds"></p>
    `
  },
})
```

### Notes
- Use `setup` for non-ref behavior. Keep markup creation in `render`, and keep ref-backed DOM work in `onFirstRender()`.
- `setup` runs only once per connected instance.
- Use `observeProps(...)` to react to prop changes. The `props` object is normalized and always usable, but it is not itself a local signal source.
```

--------------------------------

### Frontend HTML: data-on:click and data-signals

Source: https://data-star.dev/guide/backend_requests

HTML example showing how to use data-on:click to trigger a GET request and update signals and DOM.

```html
<div
    data-signals="{response: '', answer: ''}"
    data-computed:correct="$response.toLowerCase() == $answer"
>
    <div id="question"></div>
    <button data-on:click="@get('/actions/quiz')">Fetch a question</button>
    <button
        data-show="$answer != ''"
        data-on:click="$response = prompt('Answer:') ?? ''"
    >
        BUZZ
    </button>
    <div data-show="$response != ''">
        You answered “<span data-text="$response"></span>”.
        <span data-show="$correct">That is correct ✅</span>
        <span data-show="!$correct">
        The correct answer is “<span data-text="$answer"></span>” 🤷
        </span>
    </div>
</div>
```

--------------------------------

### ctx.render example: demo-user-card

Source: https://data-star.dev/reference/rocket

Example of using ctx.render in setup to imperatively rerender the component after an async fetch. It passes user data or an error to the render function, which displays loading, error, or user info. The cleanup flag prevents updates after teardown.

```javascript
rocket('demo-user-card', {
  props: ({ string, number }) => ({
    userId: number.min(1),
    fallbackName: string.default('Unknown user'),
  }),
  setup: ({ cleanup, render, props }) => {
    let cancelled = false

    ;(async () => {
      try {
        const response = await fetch('/users/' + props.userId + '.json')
        const user = await response.json()
        if (!cancelled) {
          render({}, user, null)
        }
      } catch (error) {
        if (!cancelled) {
          render({}, null, error)
        }
      }
    })()

    cleanup(() => {
      cancelled = true
    })
  },
  render: ({ html, props: { fallbackName } }, user = null, error = null) => {
    if (error) {
      return html`<p>Failed to load user.</p>`
    }
    if (!user) {
      return html`<p>Loading user...</p>`
    }
    return html`
      <article>
        <h3>${user.name ?? fallbackName}</h3>
        <p>${user.email ?? 'No email provided'}</p>
      </article>
    `
  },
})
```

--------------------------------

### Example of @post action with URL

Source: https://data-star.dev/errors/fetch_no_url_provided

Shows a button element using the @post() action with a URL argument. This example is provided in the context of the FetchNoUrlProvided error, illustrating that a URL must be provided to actions like @get().

```html
<button data-on:click="@post('/endpoint')"></button>
```

--------------------------------

### rocket('demo-stepper', ...)

Source: https://data-star.dev/reference/rocket

Example of a Rocket component using render to create a counter with typed props, local state via setup, and Datastar attributes for event handling and bindings.

```APIDOC
## rocket('demo-stepper', ...)

### Description
Defines a Rocket component named 'demo-stepper' that renders a counter with increment/decrement buttons and a display. It uses typed props, local state, and Datastar attributes for interactivity.

### Method
Component definition

### Endpoint
rocket('demo-stepper', options)

### Parameters
#### Options
- **mode** (string) - Required - 'light' for light DOM mode.
- **props** (function) - Required - Defines the component's public API with typed prop validators.
- **setup** (function) - Required - Creates local state and effects.
- **render** (function) - Required - Returns the component's DOM shape using the html tagged template.

### Request Example
```js
rocket('demo-stepper', {
  mode: 'light',
  props: ({ number, string }) => ({
    start: number.min(0),
    step: number.min(1).default(1),
    label: string.trim.default('Count'),
  }),
  setup: ({ $$, props }) => {
    $$.count = props.start
  },
  render: ({ html, props: { label, step } }) => {
    return html`
      <section class="stack gap-2">
        <h3>${label}</h3>
        <div class="row gap-2">
          <button data-on:click="$$count -= ${step}" data-attr:disabled="$$count <= 0">-</button>
          <output data-text="$$count"></output>
          <button data-on:click="$$count += ${step}">+</button>
        </div>
      </section>
    `
  },
})
```

### Response
#### Success Response
- **component** (object) - The defined custom element with the specified behavior.

#### Response Example
```js
// No explicit response; the component is registered and can be used in HTML.
```
```

--------------------------------

### Usage Example: HTML with data-signals and copy-button

Source: https://data-star.dev/examples/rocket_copy_button

The demo page owns the editable text and passes it to the component as a prop. The component keeps only its ephemeral 'copied' state in setup() so it can show feedback and clear the timeout.

```html
<div data-signals='{"myCode":"To infinity and beyond"}'>
    <input data-bind:my-code type="text" />
    <copy-button data-attr:code="$myCode"></copy-button>
</div>
```

--------------------------------

### Rocket demo-prop-normalize with overrideProp setter

Source: https://data-star.dev/reference/rocket

Example of using overrideProp to normalize a prop value by trimming and converting to string. Setup runs before initial render and Datastar apply pass, so refs are not yet available.

```javascript
rocket('demo-prop-normalize', {
  props: ({ string }) => ({
    value: string.default(''),
  }),
  setup: ({ overrideProp }) => {
    overrideProp('value', undefined, (value, setDefault) => {
      setDefault(String(value ?? '').trim())
    })
  },
})
```

--------------------------------

### Send multiple SSE events in Go

Source: https://data-star.dev/guide/backend_requests

Go example using sse.PatchElements and sse.PatchSignals to send multiple SSE events.

```Go
sse.PatchElements(`<div id="question">...</div>`)
sse.PatchElements(`<div id="instructions">...</div>`)
sse.PatchSignals([]byte(`{answer: '...', prize: '...'}`))
```

--------------------------------

### setup hook type signature

Source: https://data-star.dev/reference/rocket

Type signature for the setup hook. It runs once per connected element instance before the initial Datastar apply pass, suitable for local signals, computed state, prop observers, timers, and cleanup handlers that do not depend on rendered DOM.

```typescript
setup?: (context: SetupContext<InferProps<Defs>>) => void
```

--------------------------------

### SSE stream with multiple events

Source: https://data-star.dev/guide/getting_started

Extends the SSE example to send HAL's response and then reset the text after a few seconds.

```text
event: datastar-patch-elements
data: elements <div id="hal">
data: elements     I’m sorry, Dave. I’m afraid I can’t do that.
data: elements </div>

event: datastar-patch-elements
data: elements <div id="hal">
data: elements     Waiting for an order...
data: elements </div>

```

--------------------------------

### Host Datastar locally

Source: https://data-star.dev/guide/getting_started

Hosting the file yourself is recommended. Download the script or create your own bundle using the bundler, then include it from the appropriate path.

```html
<script type="module" src="/path/to/datastar.js"></script>
```

--------------------------------

### Ruby: Redirect with Datastar.new

Source: https://data-star.dev/how_tos/redirect_the_page_from_the_backend

Uses Datastar.new to patch an indicator element, wait 3 seconds, and redirect to '/guide'.

```ruby
datastar = Datastar.new(request:, response:)

datastar.stream do |sse|
  sse.patch_elements '<div id="indicator">Redirecting in 3 seconds...</div>'

  sleep 3

  sse.redirect '/guide'
end
```

--------------------------------

### @toggleAll() examples with filters

Source: https://data-star.dev/reference/actions

Toggles the boolean value of all matching signals. The filter object uses an `include` regular expression to match signal paths and an optional `exclude` to exclude patterns. Examples show toggling only `foo`, all signals starting with `is`, and signals starting with `settings.`.

```html
<!-- Toggles the `foo` signal only -->
<div data-signals:foo="false">
    <button data-on:click="@toggleAll({include: /^foo$/})"></button>
</div>

<!-- Toggles all signals starting with `is` -->
<div data-signals="{isOpen: false, isActive: true, isEnabled: false}">
    <button data-on:click="@toggleAll({include: /^is/})"></button>
</div>

<!-- Toggles signals starting with `settings.` -->
<div data-signals="{settings: {darkMode: false, autoSave: true}}">
    <button data-on:click="@toggleAll({include: /^settings\./})"></button>
</div>
```

--------------------------------

### C# SDK example for loading more items

Source: https://data-star.dev/how_tos/load_more_list_items

ASP.NET Core minimal API that reads the offset signal, appends a new item, updates the offset, and removes the button when the max offset is reached. Uses the Datastar service with dependency injection.

```csharp
using System.Text.Json;
using StarFederation.Datastar;
using StarFederation.Datastar.DependencyInjection;

public class Program
{
    public record OffsetSignals(int offset);

    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);
        builder.Services.AddDatastar();
        var app = builder.Build();

        app.MapGet("/more", async (IDatastarService datastarService) =>
        {
            var max = 5;
            var limit = 1;
            var signals = await datastarService.ReadSignalsAsync<OffsetSignals>();
            var offset = signals.offset;
            if (offset < max)
            {
                var newOffset = offset + limit;
                await datastarService.PatchElementsAsync($"<div>Item {newOffset}</div>", new()
                {
                    Selector = "#list",
                    PatchMode = PatchElementsMode.Append,
                });
                if (newOffset < max)
                    await datastarService.PatchSignalsAsync(new OffsetSignals(newOffset));
                else
                    await datastarService.RemoveElementAsync("#load-more");
            }
        });

        app.Run();
    }
}
```

--------------------------------

### @get() basic request

Source: https://data-star.dev/reference/actions

Sends a GET request to the specified endpoint. By default, requests include a 'Datastar-Request: true' header and a {datastar: *} object with all signals except those starting with an underscore. Signals are sent as query parameters for GET requests.

```html
<button data-on:click="@get('/endpoint')"></button>
```

--------------------------------

### Go: Backend endpoint using Datastar SDK

Source: https://data-star.dev/how_tos/poll_the_backend_at_regular_intervals

Go example using the Datastar SDK to patch elements with the current time in response to polling.

```Go
import (
    "time"
    "github.com/starfederation/datastar-go/datastar"
)

currentTime := time.Now().Format("2006-01-02 15:04:05")

sse := datastar.NewSSE(w, r)
sse.PatchElements(fmt.Sprintf(`
    <div id="time" data-on-interval__duration.5s="@get('/endpoint')">
        %s
    </div>
`, currentTime))
```

--------------------------------

### Usage Example: password-strength element

Source: https://data-star.dev/examples/rocket_password_strength

HTML usage of the custom element with an initial password prop. The component is self-contained and starts from this prop value.

```html
<password-strength password="Str0ng!Pass"></password-strength>
```

--------------------------------

### Go: Redirect with datastar.NewSSE

Source: https://data-star.dev/how_tos/redirect_the_page_from_the_backend

Uses datastar.NewSSE to patch an indicator element, wait 3 seconds, and redirect to '/guide'.

```go
import (
    "time"
    "github.com/starfederation/datastar-go/datastar"
)

sse := datastar.NewSSE(w, r)
sse.PatchElements(`
    <div id="indicator">Redirecting in 3 seconds...</div>
`)
time.Sleep(3 * time.Second)
sse.Redirect("/guide")
```

--------------------------------

### Go backend redirect using ExecuteScript

Source: https://data-star.dev/how_tos/redirect_the_page_from_the_backend

Uses the Go SDK's PatchElements and ExecuteScript methods to show an indicator, wait 3 seconds, and redirect to /guide.

```Go
import (
    "time"
    "github.com/starfederation/datastar-go/datastar"
)

sse := datastar.NewSSE(w, r)
sse.PatchElements(`
    <div id="indicator">Redirecting in 3 seconds...</div>
`)
time.Sleep(3 * time.Second)
sse.ExecuteScript(`
    window.location = "/guide"
`)
```

--------------------------------

### Rust backend: PatchElements and PatchSignals

Source: https://data-star.dev/guide/backend_requests

Rust example using datastar::prelude::* and async_stream to create an SSE stream that patches an element and signals.

```rust
use datastar::prelude::*;
use async_stream::stream;

Sse(stream! {
    // Patches elements into the DOM.
    yield PatchElements::new("<div id='question'>What do you put in a toaster?</div>").into();

    // Patches signals.
    yield PatchSignals::new("{response: '', answer: 'bread'}").into();
})
```

--------------------------------

### Usage Example: alphabet-stream element

Source: https://data-star.dev/examples/rocket_letter_stream

HTML usage of the custom element with a seed attribute. The component starts from this seed string and streams letters until Z.

```html
<alphabet-stream seed="ABCDEF"></alphabet-stream>
```

--------------------------------

### @setAll() examples with filters

Source: https://data-star.dev/reference/actions

Sets the value of all matching signals. The filter object uses an `include` regular expression to match signal paths and an optional `exclude` to exclude patterns. Examples show setting only `foo`, all signals starting with `user.`, and all signals except those ending with `_temp`.

```html
<!-- Sets the `foo` signal only -->
<div data-signals:foo="false">
    <button data-on:click="@setAll(true, {include: /^foo$/})"></button>
</div>

<!-- Sets all signals starting with `user.` -->
<div data-signals="{user: {name: '', nickname: ''}}">
    <button data-on:click="@setAll('johnny', {include: /^user\./})"></button>
</div>

<!-- Sets all signals except those ending with `_temp` -->
<div data-signals="{data: '', data_temp: '', info: '', info_temp: ''}">
    <button data-on:click="@setAll('reset', {include: /.*/, exclude: /_temp$/})"></button>
</div>
```

--------------------------------

### Usage Example: HTML with data-signals and conditional-panel

Source: https://data-star.dev/examples/rocket_conditional

Sets up the initial state with data-signals and binds the step and show-details props to the conditional-panel component using data-attr.

```html
<div data-signals='{"step":0,"showDetails":false}'>
    <conditional-panel
        data-attr:step="$step"
        data-attr:show-details="$showDetails"
    ></conditional-panel>
</div>
```

--------------------------------

### Zig backend: SSE with PatchElements and patchSignals

Source: https://data-star.dev/guide/backend_requests

Zig example using http.NewSSE() to create an SSE stream and patch elements and signals.

```zig
const datastar = @import("datastar");

var sse = http.NewSSE();
defer sse.close();

// Patches elements into the DOM.
try sse.PatchElements(
    \\<div id="question">What do you put in a toaster?</div>
    , .{});
)

// Patches signals.
try sse.patchSignals(.{
    .response: "",
    .answer: "bread"
}, .{});
```

--------------------------------

### Define a custom element with rocket()

Source: https://data-star.dev/reference/rocket

Example of defining a 'demo-counter' custom element using rocket(). It demonstrates props with codecs, setup with observeProps, and render returning HTML.

```javascript
import { rocket } from '/path/to/datastar-rocket.js'

rocket('demo-counter', {
  mode: 'light',
  props: ({ number, string }) => ({
    count: number.step(1).min(0),
    label: string.trim.default('Counter'),
  }),
  setup: ({ $$, observeProps, props }) => {
    $$.count = props.count
    observeProps(() => {
      $$.count = props.count
    }, 'count')
  },
  render: ({ html, props: { count, label } }) => {
    return html`
      <div class="stack gap-2">
        <button
          type="button"
          data-on:click="$$count += 1"
          data-text="${label} + ': ' + $$count"
        ></button>
        <template data-if="$$count !== ${count}">
          <button type="button" data-on:click="$$count = ${count}">Reset</button>
        </template>
      </div>
    `
  },
})
```

--------------------------------

### Backend Action Options

Source: https://data-star.dev/reference/actions

Describes the options object that can be passed as the second argument to all Datastar backend actions (e.g., @get, @post). Includes details on each option and an example usage.

```APIDOC
## Backend Action Options

### Description
All Datastar backend actions (e.g., `@get`, `@post`) accept a second argument of options. This section documents each available option.

### Options

- **contentType** (string) - Optional - The type of content to send. `json` sends all signals in a JSON request. `form` looks for the closest form (unless `selector` is provided), validates form elements, and sends them as a form request (no signals). Defaults to `json`.
- **filterSignals** (object) - Optional - A filter object with an `include` property (regular expression to match signal paths, defaults to `/.*/`) and an optional `exclude` property (regular expression to exclude signal paths, defaults to `/(^_|\._).*/`).
- **selector** (string|null) - Optional - Specifies a form to send when `contentType` is `form`. If `null`, the closest form is used. Defaults to `null`.
- **headers** (object) - Optional - An object containing headers to send with the request.
- **openWhenHidden** (boolean) - Optional - Whether to keep the connection open when the page is hidden. Defaults to `false` for `get` requests, and `true` for all other HTTP methods.
- **payload** (object) - Optional - Allows the fetch payload to be overridden with a custom object.
- **retry** (string) - Optional - Determines when to retry requests. Can be `'auto'` (default, retries on network errors only), `'error'` (retries on `4xx` and `5xx` responses), `'always'` (retries on all non-`204` responses except redirects), or `'never'` (disables retries). Defaults to `'auto'`.
- **retryInterval** (number) - Optional - The retry interval in milliseconds. Defaults to `1000` (one second).
- **retryScaler** (number) - Optional - A numeric multiplier applied to scale retry wait times. Defaults to `2`.
- **retryMaxWait** (number) - Optional - The maximum allowable wait time in milliseconds between retries. Defaults to `30000` (30 seconds).
- **retryMaxCount** (number) - Optional - The maximum number of retry attempts. Defaults to `10`.
- **requestCancellation** (string|AbortController) - Optional - Controls request cancellation behavior. Can be `'auto'` (default, cancels in-flight requests to the same URL using the same HTTP method), `'cleanup'` (cancels requests on element or attribute cleanup, and cancels in-flight requests to the same URL using the same HTTP method), `'disabled'` (allows concurrent requests), or an `AbortController` instance for custom control. Defaults to `'auto'`.

### Example
```html
<button data-on:click="@get('/endpoint', {
    filterSignals: {include: /^foo\./},
    headers: {
        'X-Csrf-Token': 'JImikTbsoCYQ9oGOcvugov0Awc5LbqFsZW6ObRCxuq',
    },
    openWhenHidden: true,
    requestCancellation: 'disabled',
})"></button>
```
```

--------------------------------

### Frontend HTML with data-signals and data-on:click

Source: https://data-star.dev/guide/reactive_signals

Sets up a frontend signal 'hal' and a button that triggers a GET request to '/endpoint'. The response patches the signal, and the result is displayed in a div using data-text.

```HTML
<div data-signals:hal="'...'">
    <button data-on:click="@get('/endpoint')">
        HAL, do you read me?
    </button>
    <div data-text="$hal"></div>
</div>
```

--------------------------------

### Clojure: Backend endpoint using Datastar SDK

Source: https://data-star.dev/how_tos/poll_the_backend_at_regular_intervals

Clojure example using the Datastar SDK to respond to polling requests with a patch-elements event, rendering the current time.

```Clojure
(require
  '[starfederation.datastar.clojure.api :as d*]
  '[starfederation.datastar.clojure.adapter.http-kit :refer [->sse-response on-open]])
  '[some.hiccup.library :refer [html]])

(import
  'java.time.format.DateTimeFormatter
  'java.time.LocalDateTime)

(def formatter (DateTimeFormatter/ofPattern "YYYY-MM-DD HH:mm:ss"))

(defn handle [ring-request]
   (->sse-response ring-request
     {on-open
      (fn [sse]
        (d*/patch-elements! sse
          (html [:div#time {:data-on-interval__duration.5s (d*/sse-get "/endpoint")}
                  (LocalDateTime/.format (LocalDateTime/now) formatter)])))}))

        (d*/close-sse! sse))}))
```

--------------------------------

### PHP backend redirect using ExecuteScript

Source: https://data-star.dev/how_tos/redirect_the_page_from_the_backend

Uses the PHP SDK's patchElements and executeScript methods to show an indicator, wait 3 seconds, and redirect to /guide.

```PHP
use starfederation\datastar\ServerSentEventGenerator;

$sse = new ServerSentEventGenerator();
$sse->patchElements(`
    <div id="indicator">Redirecting in 3 seconds...</div>
`);
sleep(3);
$sse->executeScript(`
    window.location = "/guide"
`);
```

--------------------------------

### Rocket loop rendering with data-for

Source: https://data-star.dev/reference/rocket

Example of rendering a list with <template data-for> in Rocket. The setup function defines $$letters as an array, and the render function uses data-for to iterate over it, displaying the index and letter.

```javascript
rocket('demo-letter-list', {
  mode: 'light',
  setup: ({ $$ }) => {
    $$.letters = ['A', 'B', 'C']
  },
  render: ({ html }) => html`
    <ul>
      <template data-for="letter, row in $$letters">
        <li>
          <strong data-text="row + 1"></strong>
          <span data-text="letter"></span>
        </li>
      </template>
    </ul>
  `,
})
```

--------------------------------

### Python: Redirect with ServerSentEventGenerator

Source: https://data-star.dev/how_tos/redirect_the_page_from_the_backend

Uses ServerSentEventGenerator from datastar_py to patch an indicator element, wait 3 seconds, and redirect to '/guide'.

```python
from datastar_py import ServerSentEventGenerator as SSE
from datastar_py.sanic import datastar_response

@app.get("/redirect")
@datastar_response
async def redirect_from_backend():
    yield SSE.patch_elements('<div id="indicator">Redirecting in 3 seconds...</div>')
    await asyncio.sleep(3)
    yield SSE.redirect("/guide")
```

--------------------------------

### Kotlin: Backend endpoint using Datastar SDK

Source: https://data-star.dev/how_tos/poll_the_backend_at_regular_intervals

Kotlin example using the Datastar SDK to patch elements with the current time in response to polling.

```Kotlin
val now: LocalDateTime = currentTime()

val generator = ServerSentEventGenerator(response)

generator.patchElements(
    elements =
        """
        <div id="time" data-on-interval__duration.5s="@get('/endpoint')">
            $now
        </div>
        """.trimIndent(),
)
```

--------------------------------

### Send GET request with @get action

Source: https://data-star.dev/guide/getting_started

Sends a GET request to '/endpoint' on click, with a target div for morphing.

```html
<button data-on:click="@get('/endpoint')">
    Open the pod bay doors, HAL.
</button>
<div id="hal"></div>
```

--------------------------------

### Custom Codec Example

Source: https://data-star.dev/reference/rocket

Example of creating a custom percent codec and using it in a Rocket component.

```APIDOC
## Custom Codec Example

### Description
Example of creating a custom percent codec and using it in a Rocket component.

### Code Example
```javascript
import { createCodec, rocket } from '/path/to/datastar-rocket.js'

let percent = createCodec({
    decode(value) {
      let text = String(value ?? '').trim().replace(/%$/, '')
      let number = Number.parseFloat(text)
      return Number.isFinite(number)
        ? Math.max(0, Math.min(100, number))
        : 0
    },
    encode(value) {
      return String(Math.max(0, Math.min(100, value)))
    },
})

rocket('demo-meter', {
  props: ({ string }) => ({
    value: percent.default(50),
    label: string.trim.default('Progress'),
  }),
})
```

### Notes
- The `percent` codec clamps values between 0 and 100.
- The `string` codec is used with `.trim` and `.default`.
```

--------------------------------

### Kotlin backend redirect using ExecuteScript

Source: https://data-star.dev/how_tos/redirect_the_page_from_the_backend

Uses the Kotlin SDK's patchElements and executeScript methods to show an indicator, wait 3 seconds, and redirect to /guide.

```Kotlin
val generator = ServerSentEventGenerator(response)

generator.patchElements(
    elements =
        """
        <div id="indicator">Redirecting in 3 seconds...</div>
        """.trimIndent(),
)

Thread.sleep(3 * ONE_SECOND)

generator.executeScript(
    script = "window.location.href = '/success'",
)
```

--------------------------------

### Clojure: Redirect with helper method

Source: https://data-star.dev/how_tos/redirect_the_page_from_the_backend

Clojure example using the d*/redirect! helper method that automatically wraps the redirect in setTimeout, so you don't have to worry about Firefox's URL replacement behavior.

```clojure
(require
  '[starfederation.datastar.clojure.api :as d*]
  '[starfederation.datastar.clojure.adapter.http-kit :refer [->sse-response on-open]]
  '[some.hiccup.library :refer [html]])


(defn handler [ring-request]
  (->sse-response ring-request
    {on-open
      (fn [sse]
        (d*/patch-elements! sse
          (html [:div#indicator "Redirecting in 3 seconds..."]))
        (Thread/sleep 3000)
        (d*/redirect! sse "/guide")
        (d*/close-sse! sse))}))
```

--------------------------------

### Repeated @get actions in Datastar buttons

Source: https://data-star.dev/how_tos/keep_datastar_code_dry

Shows three buttons each with the same @get('/endpoint') action, illustrating the repetition problem.

```html
<button data-on:click="@get('/endpoint')">Click me</button>
<button data-on:click="@get('/endpoint')">No, click me!</button>
<button data-on:click="@get('/endpoint')">Click us all!</button>
```

--------------------------------

### data-on-raf example incrementing count

Source: https://data-star.dev/reference/attributes

Runs the expression on every requestAnimationFrame event. This example increments the $count signal on each frame.

```HTML
<div data-on-raf="$count++"></div>
```

--------------------------------

### File upload form with data-bind and data-on:click

Source: https://data-star.dev/examples/file_upload

Creates a file input bound to the 'files' signal and a submit button that posts the files to '/examples/file_upload' when clicked. The button is disabled when no files are selected. Files are automatically encoded as base64. Uploading a file larger than 1 MiB will result in a console error.

```html
<label>
    <p>Pick anything less than 1MB</p>
    <input type="file" data-bind:files multiple/>
</label>
<button
    class="warning"
    data-on:click="$files.length && @post('/examples/file_upload')"
    data-attr:disabled="!$files.length"
>
    Submit
</button>
```

--------------------------------

### data-on-resize example incrementing count

Source: https://data-star.dev/reference/attributes

Runs the expression whenever the element's dimensions change. This example increments the $count signal on each resize event.

```HTML
<div data-on-resize="$count++"></div>
```

--------------------------------

### data-on-signal-patch-filter examples

Source: https://data-star.dev/reference/attributes

Filters which signals to watch using include and/or exclude regular expressions. Three examples show include only, exclude only, and combined filters.

```html
<!-- Only react to counter signal changes -->
<div data-on-signal-patch-filter="{include: /^counter$/}"></div>

<!-- React to all changes except those ending with "changes" -->
<div data-on-signal-patch-filter="{exclude: /changes$/}"></div>

<!-- Combine include and exclude filters -->
<div data-on-signal-patch-filter="{include: /user/, exclude: /password/}"></div>
```

--------------------------------

### Python backend redirect using ExecuteScript

Source: https://data-star.dev/how_tos/redirect_the_page_from_the_backend

Uses the Python SDK's patch_elements and execute_script methods to show an indicator, wait 3 seconds, and redirect to /guide.

```Python
from datastar_py import ServerSentEventGenerator as SSE
from datastar_py.sanic import datastar_response

@app.get("/redirect")
@datastar_response
async def redirect_from_backend():
    yield SSE.patch_elements('<div id="indicator">Redirecting in 3 seconds...</div>')
    await asyncio.sleep(3)
    yield SSE.execute_script('window.location = "/guide"')
```

--------------------------------

### C#: Backend endpoint using Datastar SDK

Source: https://data-star.dev/how_tos/poll_the_backend_at_regular_intervals

C# example using the Datastar service to patch elements with the current time in response to polling.

```C#
using StarFederation.Datastar.DependencyInjection;

app.MapGet("/endpoint", async (IDatastarService datastarService) =>
{
    var currentTime = DateTime.Now.ToString("yyyy-MM-dd hh:mm:ss");
    await datastarService.PatchElementsAsync($"""
        <div id="time" data-on-interval__duration.5s="@get('/endpoint')">
            {currentTime}
        </div>
    """);
});
```

--------------------------------

### @get(uri: string, options={ })

Source: https://data-star.dev/reference/actions

Sends a GET request to the backend using the Fetch API. Signals are sent as query parameters by default. Supports options like openWhenHidden and contentType.

```APIDOC
## @get(uri: string, options={ })

### Description
Sends a `GET` request to the backend using the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). The URI can be any valid endpoint, and the response type any of the allowed [response types](https://data-star.dev/reference/actions#response-handling), or a `204 No Content` response if the response body is empty.

### Method
GET

### Endpoint
`uri` (string) - The endpoint to send the request to.

### Parameters
#### Options
- **openWhenHidden** (boolean) - Optional - If `true`, keeps the SSE connection open when the page is hidden. Default is `false`.
- **contentType** (string) - Optional - Set to `'form'` to send form-encoded requests using `application/x-www-form-urlencoded` encoding.
- **filterSignals** (object) - Optional - Allows including or excluding specific signals using regular expressions.

### Request Example
```html
<button data-on:click="@get('/endpoint')"></button>
```

### Response
#### Success Response
- 204 No Content if the response body is empty.
- Any allowed response type.

### Notes
- By default, requests are sent with a `Datastar-Request: true` header and a `{datastar: *}` object containing all existing signals, except those beginning with an underscore.
- When using a `get` request, the signals are sent as a query parameter.
- When the page is hidden, the SSE connection is closed by default and reopened when the page becomes visible again. Set `openWhenHidden: true` to keep it open.
- Form encoded requests can be sent by setting `contentType: 'form'`.
- Multipart/form-data encoding can be used by setting the form element's `enctype` attribute to `multipart/form-data`.
```

--------------------------------

### Biome config override for Rocket example files

Source: https://data-star.dev/reference/rocket

Biome configuration override that disables the noTemplateCurlyInString rule for Rocket example files, allowing intentional ${...} expressions in template literals.

```json
{
  "overrides": [
    {
      "includes": ["site/shared/static/rocket/**/*.js"],
      "linter": {
        "rules": {
          "suspicious": {
            "noTemplateCurlyInString": "off"
          }
        }
      }
    }
  ]
}
```

--------------------------------

### Rocket demo-host-methods with defineHostProp

Source: https://data-star.dev/reference/rocket

Example of defining read-only host properties and methods using defineHostProp. The 'version' property returns a string, and 'reset' is a method that logs to console.

```javascript
rocket('demo-host-methods', {
  setup: ({ defineHostProp }) => {
    defineHostProp('version', {
      get() {
        return '1'
      },
    })
    defineHostProp('reset', {
      value() {
        console.log('reset')
      },
    })
  },
})
```

--------------------------------

### Rocket Flow Node Component Setup

Source: https://data-star.dev/examples/rocket_flow

Defines the flow-node component with props for position, label, and size, and setup logic to collect custom content or create default SVG content.

```javascript
997rocket('flow-node', {
 998  props: ({ number, string }) => ({
 999    x: number,
1000    y: number,
1001    label: string,
1002    width: number.min(1).default(DEFAULT_NODE_WIDTH),
1003    height: number.min(1).default(DEFAULT_NODE_HEIGHT),
1004  }),
1005  setup: ({ cleanup, effect, host, props }) => {
1006    host.style.display = 'none'
1007
1008    const collectCustomContent = () => {
1009      const fragment = document.createDocumentFragment()
1010      host.childNodes.forEach((child) => {
1011        if (
1012          child.nodeType === Node.ELEMENT_NODE &&
1013          child.nodeName.toUpperCase() === 'TEMPLATE'
1014        )
1015          return
1016        const clone = cloneNodeIntoSvg(child)
1017        if (!clone) return
1018        if (clone.nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
1019          fragment.append(...Array.from(clone.childNodes))
1020        } else {
1021          fragment.append(clone)
1022        }
1023      })
1024      return fragment.childNodes.length ? fragment : null
1025    }
1026
1027    const createDefaultContent = () => {
1028      const fragment = document.createDocumentFragment()
1029      const svg = document.createElementNS(SVG_NS, 'svg')
1030      const rect = document.createElementNS(SVG_NS, 'rect')
1031      const text = document.createElementNS(SVG_NS, 'text')
1032      svg.setAttribute('width', String(props.width))
1033      svg.setAttribute('height', String(props.height))
1034      svg.setAttribute('viewBox', `0 0 ${props.width} ${props.height}`)
1035      svg.setAttribute('data-default-node', '')
1036      rect.setAttribute('rx', '12')
1037      rect.setAttribute('ry', '12')
1038      rect.setAttribute('width', String(props.width))
```

--------------------------------

### Example of missing property name in data-bind __prop modifier

Source: https://data-star.dev/errors/bind_prop_name_missing

This example shows an incorrect usage of the `data-bind` attribute with the `__prop` modifier, missing the required property name, which triggers the `BindPropNameMissing` error.

```html
<my-toggle data-bind:is-checked__prop.checked></my-toggle>
```

--------------------------------

### Practical use-case with toggleAll

Source: https://data-star.dev/guide/backend_requests

Tracks open/closed state of menus on desktop and mobile, and uses toggleAll to toggle all menus at once.

```html
<div data-signals="{menu: {isOpen: {desktop: false, mobile: false}}}">
    <button data-on:click="@toggleAll({include: /^menu\.isOpen\./})">
        Open/close menu
    </button>
</div>
```

--------------------------------

### Ruby backend redirect using ExecuteScript

Source: https://data-star.dev/how_tos/redirect_the_page_from_the_backend

Uses the Ruby SDK's patch_elements and execute_script methods to show an indicator, wait 3 seconds, and redirect to /guide.

```Ruby
datastar = Datastar.new(request:, response:)

datastar.stream do |sse|
  sse.patch_elements '<div id="indicator">Redirecting in 3 seconds...</div>'
  sleep 3
  sse.execute_script 'window.location = "/guide"'
end
```

--------------------------------

### Example of data-computed object syntax with functions

Source: https://data-star.dev/errors/computed_expected_function

Shows the correct usage of data-computed with object syntax where each leaf value is a function. The example uses arrow functions for 'foo' and 'bar', with 'bar' referencing '$foo'.

```html
<div data-computed="{foo: () => 1, bar: () => $foo + 1}"></div>
```

--------------------------------

### Use the demo-counter custom element

Source: https://data-star.dev/reference/rocket

HTML example showing how to use the defined demo-counter element in a page, with a script tag loading the component module.

```html
<script type="module" src="/path/to/demo-counter.js"></script>

<demo-counter count="5" label="Inventory"></demo-counter>
```
Tokens:
Raw