### Install StarHTML

Source: https://github.com/banditburai/starhtml/blob/main/README.md

Install the StarHTML package using pip.

```bash
pip install starhtml
```

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

### Clone and Set Up StarHTML Repository

Source: https://github.com/banditburai/starhtml/blob/main/README.md

Clone the StarHTML repository and install development dependencies using `uv` or `pip`.

```bash
git clone https://github.com/banditburai/starhtml.git
cd starhtml
uv sync  # or pip install -e ".[dev]"
pytest && ruff check .
```

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

### Timeline Tab Setup Script

Source: https://github.com/banditburai/starhtml/blob/main/docs/plans/2026-02-17-debugger-timeline-tab.md

Includes a setup script section that imports the debugger timeline JavaScript, initializes it, subscribes to updates, and schedules renders using requestAnimationFrame. It also handles active tab switching for performance.

```javascript
Add setup script section that imports `debugger-timeline.js`, calls `init()`, subscribes to updates, and schedules renders via `requestAnimationFrame`.
```

```javascript
Wire active tab switching: only render timeline when tab is active (performance, same pattern as other tabs).
```

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

### Add Route/URL to Start Event Preview

Source: https://github.com/banditburai/starhtml/blob/main/docs/plans/2026-02-15-debugger-phase-1.5.md

Includes the route or URL associated with a 'start' event in its preview. This information is typically derived from an attribute like `data-on-click` on the triggering element.

```string
Add the route/URL to the `start` event preview (from the element's `data-on-click` or similar attribute).
```

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

### Send GET Request with @get()

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Initiate a GET request using the Fetch API. By default, it includes Datastar headers and query parameters derived from signals. Configure options like `openWhenHidden` or `contentType` for specific behaviors.

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

```html
<button data-on:click="@get('/endpoint', {openWhenHidden: true})"></button>
```

```html
<button data-on:click="@get('/endpoint', {contentType: 'form'})"></button>
```

```html
<form enctype="multipart/form-data">
    <input type="file" name="file" />
    <button data-on:click="@get('/endpoint', {contentType: 'form'})"></button>
</form>
```

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

### Register Startup and Shutdown Handlers (Constructor Lists)

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Register startup and shutdown handlers using constructor lists for quick setup. Handlers can be sync or async and optionally accept the app instance.

```python
app, rt = star_app(
    on_startup=[init_db, warm_cache],
    on_shutdown=[close_db],
)
```

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

### Make HTTP Requests with get(), post(), delete()

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Use HTTP methods like get(), post(), and delete() to make requests from the browser. By default, all signals are sent as the request body. Use the `payload` option to send specific data.

```python
# All signal values are sent automatically — no need to specify data
data_on_click=get("/api/data")
data_on_click=post("/api/submit")
data_on_click=delete(f"/api/items/{item_id}")  # item_id is a Python variable baked into the URL at render time
```

```python
# Conditional requests
data_on_click=is_valid.then(post("/api/submit"))
```

```python
# Send only "text" — derived from a browser-side DOM value
data_on_blur=post("/api/edit", payload={"text": js("evt.target.innerText.trim()")})
```

```python
# Set content type for form submissions
data_on_click=post("/api/submit", contentType="form")
```

```python
# Send only signals whose names match a regex
data_on_click=post("/api/submit", filterSignals="name|email")
```

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

### WebSocket Support in StarHTML

Source: https://context7.com/banditburai/starhtml/llms.txt

Integrate real-time bidirectional communication using WebSocket endpoints. Use `setup_ws(app)` to get a broadcast function and define custom handlers with `@app.ws()`.

```python
from starhtml import *

app, rt = star_app()
send = setup_ws(app)  # Returns broadcast function

# Custom WebSocket handler
@app.ws("/chat")
async def chat_handler(ws, data, send):
    # data contains parsed JSON from client
    message = data.get("message", "")
    await send(Div(f"Echo: {message}", id="output"))

# With connection lifecycle
@app.ws("/live", conn=on_connect, disconn=on_disconnect)
async def live_handler(ws, data):
    pass

async def on_connect(ws):
    print("Client connected")

async def on_disconnect(ws):
    print("Client disconnected")

```

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

### Causal Linking Trace Example

Source: https://github.com/banditburai/starhtml/blob/main/docs/designs/2026-02-17-debugger-timeline-tab.md

Illustrates the hierarchical structure of events within a trace, showing parent-child relationships and depth.

```text
traceId=7:
  [user-action]  click #increment-btn          parentId=null  depth=0
    [sse-lifecycle]  started /increment         parentId=0     depth=1
    [signal-change]  count: 3 -> 4              parentId=0     depth=1
      [effect-eval]  effect#0 (text) 0.1ms     parentId=2     depth=2
        [dom-mutation]  #counter text "3"->"4"   parentId=3     depth=3
    [sse-lifecycle]  finished (45ms)            parentId=0     depth=1
```

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

### Send GET Request with @get() Action

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

The `@get()` action sends a GET request to a specified URL. The backend can respond with HTML elements that will be morphed into the existing DOM, updating the UI.

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

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

### JavaScript Alert from Backend

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Execute JavaScript code on the frontend that is sent from the backend. This example shows a simple alert message being displayed.

```javascript
alert('This mission is too important for me to allow you to jeopardize it.')
```

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

### Toggle All Nested Menus

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

This example demonstrates toggling the open/closed state of multiple nested menus using a single button. The `toggleAll()` action with an `include` filter targets specific nested signals.

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

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

### Common Event Handling in StarHTML

Source: https://github.com/banditburai/starhtml/blob/main/web/API.md

Provides examples of common event handlers for user interactions like clicks, input changes, form submissions, and general value changes.

```html
`data_on_click`=action         # Click handler
```

```html
`data_on_input`=update_value   # Input change
```

```html
`data_on_submit`=save_form     # Form submission
```

```html
`data_on_change`=validate      # Value change
```

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

### Relay for Real-time Pub/Sub

Source: https://context7.com/banditburai/starhtml/llms.txt

Implement real-time updates using `Relay` for in-process event broadcasting. Install `Relay` with `relay.install(app)` and use `relay.stream()` to subscribe to events. Events can be emitted as HTML elements or signals.

```python
from starhtml import *

app, rt = star_app()
relay = Relay()
relay.install(app)  # Wire shutdown to app lifespan

@rt("/")
def home():
    return Div(
        (message := Signal("message", "")),

        Input(data_bind=message, placeholder="Type a message"),
        Button("Send", data_on_click=post("/send")),

        # Subscribe to real-time updates
        Div(id="messages", data_on_load=get("/subscribe")),
    )

@rt("/subscribe")
@sse
async def subscribe():
    # Stream events from relay until shutdown
    async for item in relay.stream():
        yield item

@rt("/send", methods=["POST"])
def send_message(message: str):
    # Broadcast to all subscribers
    relay.emit_element(
        Div(message, cls="message"),
        "#messages",
        "append"
    )
    return signals(message="")  # Clear input

# Alternative: emit signals to all clients
@rt("/notify", methods=["POST"])
def notify():
    relay.emit_signals({"notification": "New update available!"})
    return Response(status_code=204)

```

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

### Timeline Render Scheduling

Source: https://github.com/banditburai/starhtml/blob/main/docs/plans/2026-02-17-debugger-timeline-tab.md

Implements `scheduleTimelineRender` in the setup script for incremental appending of new traces or full re-rendering on filter changes. This optimizes performance by only updating necessary parts of the UI.

```javascript
Implement `scheduleTimelineRender()` in the setup script. Pattern: incremental append for new traces, full re-render on filter change.
```

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

### Correct Positional vs Keyword Arguments

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Ensures that positional arguments (content, setup code) always precede keyword arguments (configuration, attributes) to avoid `SyntaxError: positional argument follows keyword argument`.

```python
# ❌ ERROR: Positional after keyword
Div(
    cls="container",    # Keyword first
    "Hello World"       # ❌ Positional after keyword = SYNTAX ERROR
)

# ✅ CORRECT: Content first, then configuration
Div(
    "Hello World",      # ✅ Content (positional) first
    Button("Click"),    # ✅ More content
    
    cls="container",    # ✅ Configuration (keywords) after
    data_on_click=handler
)
```

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

### Flash Prevention for Modals

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Start modals hidden using `style="display: none"` by default to prevent content flash before the `data_show` signal makes them visible.

```python
# ✅ Always start hidden to prevent flash
Div(
    "Modal content",
    style="display: none",     # Hidden by default
    data_show=is_modal_open    # Shows when signal is true
)
```

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

### Test Attribute Starts With Selector

Source: https://github.com/banditburai/starhtml/blob/main/tests/browser/test_attribute_selector.html

Demonstrates the use of the attribute starts-with selector ('^=') in querySelectorAll. This selects elements where an attribute's value begins with a specified string. Note: The example uses an empty string, which might not be a typical use case but tests selector parsing.

```javascript
const test2 = document.querySelectorAll('\\[data-on-resize^=""\\]');
console.log('Starts with [data-on-resize^=""]:', test2.length);
```

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

### Register Startup and Shutdown Handlers (Lifespan Context Manager)

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Use a lifespan context manager for paired startup and shutdown logic, such as opening and closing a database connection. This is the recommended approach for managing paired resources.

```python
from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app):
    db = await connect_db()
    yield
    await db.close()

app, rt = star_app(lifespan=lifespan)
```

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

### Lifecycle Handlers with StarHTML

Source: https://context7.com/banditburai/starhtml/llms.txt

Demonstrates various methods for registering startup and shutdown handlers for application lifecycle events in StarHTML.

```python
from starhtml import *
from contextlib import asynccontextmanager

# Option 1: Constructor lists
app, rt = star_app(
    on_startup=[init_db, warm_cache],
    on_shutdown=[close_db],
)

# Option 2: Lifespan context manager
@asynccontextmanager
async def lifespan(app):
    db = await connect_db()
    app.state.db = db
    yield
    await db.close()

app, rt = star_app(lifespan=lifespan)

# Option 3: Decorator
@app.on_event("startup")
async def init_cache():
    app.state.cache = {}

@app.on_event("shutdown")
def cleanup():
    print("Shutting down...")

# Option 4: Programmatic
app.add_lifecycle_handler("startup", init_db)
app.add_lifecycle_handler("shutdown", close_db)
```

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

### Production Icon Scanning Command

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Demonstrates the command-line interface for scanning project files to pre-cache all used icons. This is crucial for production builds to ensure icons are available locally.

```bash
# In CI/CD or before deploy: scan source and pre-cache all icons
starhtml icons scan web/ src/

# Commit the cache or bake into Docker image
git add .starhtml/icons/

# In production: inline_icons=True loads from disk cache at startup
# Zero API calls, zero external dependencies
```

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

### Basic Icon Usage in StarHTML

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Demonstrates how to use the Icon component with different icon sets using the 'prefix:name' format. Ensure 'starhtml' is imported.

```python
from starhtml import *

# Icons use "prefix:name" format from any Iconify-compatible set
Icon("lucide:home")                    # Lucide icon
Icon("mdi:account")                    # Material Design
Icon("ph:star")                        # Phosphor
Icon("tabler:settings")               # Tabler
```

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

### Register Startup and Shutdown Handlers (Programmatic)

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Register startup and shutdown handlers programmatically using `add_lifecycle_handler`. This approach is useful when handlers are managed by plugins or external configuration.

```python
app.add_lifecycle_handler("startup", init_db)
app.add_lifecycle_handler("shutdown", close_db)
```

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

### Commit Pending Style Cleanup

Source: https://github.com/banditburai/starhtml/blob/main/docs/plans/2026-02-15-debugger-phase-1.5.md

Before starting debugger tasks, commit any pending style cleanup and demo fix changes.

```bash
git add -A && git commit -m "refactor(debugger): style cleanup + fix demo"
```

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

### Managing CSS Classes with StarHTML

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Illustrates how to apply static CSS classes using `cls` for SSR, and dynamically toggle or set classes using `data_class_*` and `data_attr_class` for reactive styling.

```python
# CSS classes - including Tailwind, Daisy, custom classes, etc.
cls="btn bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"  # SSR classes
```

```python
data_class_active=is_active                             # Toggle single class (no special chars)
```

```python
data_attr_class=theme.if_("dark:bg-gray-900 dark:text-white", "bg-white text-black")  # Class template
```

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

### Initialize Debug Context

Source: https://github.com/banditburai/starhtml/blob/main/docs/designs/2026-02-17-debugger-timeline-tab.md

Initializes the debug context if it's not already set. This is typically done at the start of request processing.

```python
if debug_ctx is None:
    debug_ctx = _request_ctx.get(None)
```

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

### Preserve Multiple Attributes

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Multiple attributes can be preserved by separating them with a space in the `data-preserve-attr` value. This example preserves both `open` and `class`.

```html
<details open class="foo" data-preserve-attr="open class">
    <summary>Title</summary>
    Content
</details>
```

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

### Run Debugger Demo

Source: https://github.com/banditburai/starhtml/blob/main/docs/plans/2026-02-15-debugger-phase-1.5.md

Manually tests the debugger by running the Python web server.

```bash
uv run python/web/demos/30_debugger_demo.py
```

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

### Smooth Transitions with Opacity and data_style_opacity

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Applies an opacity transition for a smoother show/hide effect, controlled by a signal. Requires initial opacity and transition styles.

```python
Div(
    "Modal content", 
    style="opacity: 0; transition: opacity 0.3s",  # Invisible + smooth transition
    data_style_opacity=is_modal_open.if_("1", "0") # Fades in/out
)
```

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

### Preserve Single Attribute

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

The `data-preserve-attr` attribute ensures that specified attributes are not overwritten during DOM morphing. This example preserves the `open` attribute.

```html
<details open data-preserve-attr="open">
    <summary>Title</summary>
    Content
</details>
```

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

### Icon Coloring and Styling

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Shows how to style icons using text color classes (e.g., `text-red-500`) and spacing utilities. Also demonstrates integrating icons within a Button component.

```python
# Colors inherit via currentColor — use text-* classes
Icon("lucide:heart", cls="text-red-500 size-6")
Icon("lucide:star", cls="text-amber-400 size-5")

# Spacing classes work on the wrapper span
Icon("lucide:home", cls="mr-2")

# In buttons
Button(
    Icon("lucide:download", cls="size-4 mr-2"),
    "Download",
    cls="inline-flex items-center px-4 py-2 bg-blue-600 text-white rounded",
)
```

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

### Benchmark Initialization and Status Updates

Source: https://github.com/banditburai/starhtml/blob/main/tests/browser/benchmark_handlers.html

Initializes benchmark variables, loads baseline data from localStorage, and provides functions to update the UI with benchmark status messages.

```javascript
let currentResults = null;
let baselineResults = null;
// Load baseline from localStorage if exists
const stored = localStorage.getItem('starhtml-benchmark-baseline');
if (stored) {
 baselineResults = JSON.parse(stored);
}
function updateStatus(message, type = 'running') {
 const status = document.getElementById('status');
 status.className = `status ${type}`;
 status.textContent = message;
}
```

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

### Disable Request Cancellation with @get()

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Prevent a new request from canceling an ongoing one by setting `requestCancellation` to 'disabled'. This allows for concurrent requests on the same element.

```html
<!-- Allow concurrent requests -->
<button data-on:click="@get('/endpoint', {requestCancellation: 'disabled'})">Allow Multiple</button>
```

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

### Debounce Signal Patch Event

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Apply modifiers like `__debounce` to control event listener timing. This example debounces the `signal-patch` event for 500ms.

```html
<div data-on:signal-patch__debounce.500ms="doSomething()"></div>
```

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

### Create StarHTML Application

Source: https://context7.com/banditburai/starhtml/llms.txt

Use `star_app` to create an application instance with routing, sessions, middleware, and optional database integration. Configure features like live reload, debug mode, and custom headers.

```python
from starhtml import *

# Basic app creation
app, rt = star_app()

# With database integration (SQLite via fastlite)
app, rt, items, Item = star_app(
    db_file="data.db",
    items=dict(id=int, title=str, done=bool),
    title="Todo App",
    debug=True,
    devtools=True,
    live=True,  # Enable live reload
    hdrs=[Script(src="https://cdn.tailwindcss.com")],
)

# With custom session and middleware
app, rt = star_app(
    secret_key="my-secret-key",
    session_cookie="my_session",
    max_age=7 * 24 * 3600,  # 7 days
    middleware=[compression()],  # Built-in gzip/brotli
    on_startup=[init_database],
    on_shutdown=[close_database],
    inline_icons=True,  # Server-side SVG rendering
)
```

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

### JavaScript Integration with StarHTML

Source: https://context7.com/banditburai/starhtml/llms.txt

Embeds raw JavaScript and utilizes browser APIs within StarHTML components. Includes examples for signals, buttons, and template literals.

```python
from starhtml import *

app, rt = star_app()

@rt("/")
def home():
    return Div(
        (timestamp := Signal("timestamp", js("Date.now()")),
        (copied := Signal("copied", False)),

        # Raw JavaScript expressions
        Button(
            "Confirm Delete",
            data_on_click=js("confirm('Are you sure?') && ") + delete("/api/item"),
        ),

        # Browser APIs
        Button(
            "Copy to Clipboard",
            data_on_click=[
                js("navigator.clipboard.writeText($message)"),
                copied.set(True),
                set_timeout(copied.set(False), 2000),
            ],
        ),
        Span(data_text=copied.if_("Copied!", ""), cls="text-green-500"),

        # Global JS objects (pre-defined)
        Button("Log", data_on_click=console.log("Debug:", message)),
        Span(data_text=Math.round(value * 100) / 100),

        # Template literal for reactive string formatting
        P(data_text="Hello " + name + "!"),

        # f_() for complex templates with multiple signals
        P(data_text=f_("Welcome {n}, you have {c} items", n=name, c=count)),
    )
```

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

### Setting CSS Properties with StarHTML

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Demonstrates how to apply CSS properties directly using the `style` attribute for SSR, or reactively using `data_style_*` and `data_attr_style` for dynamic styling.

```python
# CSS properties - for colors, dimensions, positioning, etc.
style="background-color: red; font-size: 16px"          # SSR CSS properties
```

```python
data_style_width=progress + "px"                        # Reactive CSS property
```

```python
data_attr_style=f("background-color: {color}", color=theme_color)  # CSS template
```

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

### Example of a Datastar runtime error log

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Datastar logs descriptive errors to the console when attributes are used incorrectly, including a link to a context-aware error page for more information.

```text
Uncaught datastar runtime error: textKeyNotAllowed
More info: https://data-star.dev/errors/runtime/text_key_not_allowed?...
Context: { ... }
```

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

### Running the StarHTML Benchmark

Source: https://github.com/banditburai/starhtml/blob/main/tests/browser/benchmark_handlers.html

Asynchronously runs the full benchmark suite for a specified number of elements, updates the status, and displays the formatted results. Requires the HandlerBenchmark class to be defined.

```javascript
async function runBenchmark(elementCount) {
 updateStatus(`Running benchmark with ${elementCount} elements...`, 'running');
 try {
  const benchmark = new HandlerBenchmark();
  const results = await benchmark.runAll(elementCount);
  currentResults = results;
  // Display results
  const resultsDiv = document.getElementById('results');
  resultsDiv.innerHTML = formatResults(resul
```

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

### Multiple Statements in Datastar Expressions

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Execute multiple statements within a single Datastar expression by separating them with semicolons. This example updates a signal and then triggers a POST request.

```html
<div data-signals:foo="1">
    <button data-on:click="$landingGearRetracted = true; @post('/launch')">
        Force launch
    </button>
</div>
```

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

### Basic Reactivity Patterns

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Demonstrates how Signals can be used to control element visibility, display text, bind input values, and conditionally apply CSS classes.

```python
# 2. Basic reactivity
data_show=is_visible                        # Show/hide elements
data_text=name                              # Display signal value
data_bind=name                              # Two-way form/input binding
data_class_active=is_visible                # Conditional CSS class
```

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

### Run All Unit Tests

Source: https://github.com/banditburai/starhtml/blob/main/tests/unit/README.md

Execute all unit tests within the tests/unit/ directory. Use the -v flag for verbose output.

```bash
uv run pytest tests/unit/ -v
```

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

### Verify Datastar Patches

Source: https://github.com/banditburai/starhtml/blob/main/patches/README.md

Run this command to verify that all applied patches are correct on the currently built Datastar file.

```python
python patches/verify_datastar_patches.py
```

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

### Accessing Element Reference in Datastar Expressions

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Use the 'el' variable within Datastar expressions to reference the current element. This example displays the 'id' attribute of the div element.

```html
<div id="foo" data-text="el.id"></div>
```

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

### StarHTML Debug Trace Markdown Format

Source: https://github.com/banditburai/starhtml/blob/main/docs/designs/2026-02-17-debugger-timeline-tab.md

An example of the markdown format used for exporting StarHTML debug traces. It includes context, events, signal changes, and diagnostic notes.

```markdown
## StarHTML Debug Trace

Captured: 2026-02-17 14:23:07 - 14:23:08 (1.5s)
Framework: StarHTML + Datastar (SSE reactivity)

### Page Context
Components: <status-panel>, <nav-bar>
Signals at start: status="unsaved", form.dirty=true

### Events
14:23:07.412  [start]   save_form    POST /api/save
14:23:07.823  [elements] poll_status  morph #status-panel (+0 -0 ~2)
14:23:07.891  [signals]  save_form    {"status":"saved"}
14:23:07.893  [elements] save_form    morph #status-panel (+0 -0 ~2)

### Signal Changes
  status: "unsaved" → "saved" (via save_form)

### Diagnostic Notes
- RACE: Two SSE responses targeted #status-panel within 70ms
- FLASH: #status-panel class changed twice in 70ms
```

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

### Simple Class Toggling with data_class_*

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Demonstrates the use of `data_class_*` for simple class toggling, which works reliably for class names without special characters.

```python
# Simple class names work with data_class_*
data_class_active=is_active        # Toggles "active" class ✓
```

```python
data_class_hidden=~is_visible      # Toggles "hidden" class ✓
```

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

### Opt Out of Datastar Patching

Source: https://github.com/banditburai/starhtml/blob/main/patches/README.md

Initialize StarApp with 'cdn' to serve vanilla Datastar from a CDN. Note that Shadow DOM components requiring the scan patch will not function.

```python
app, rt = star_app(datastar="cdn")
```

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

### Run Specific Test Class

Source: https://github.com/banditburai/starhtml/blob/main/tests/unit/README.md

Execute tests belonging to a specific class within a test file, for example, TestThrottlingTransformation in test_event_handlers.py. Use the -v flag for verbose output.

```bash
uv run pytest tests/unit/test_event_handlers.py::TestThrottlingTransformation -v
```

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

### Manage Request Cancellation with Custom AbortController

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Control request cancellation manually using an `AbortController`. This allows starting and canceling requests on demand, providing fine-grained control over asynchronous operations.

```html
<!-- Custom abort controller -->
<div data-signals:controller="new AbortController()">
    <button data-on:click="@get('/endpoint', {requestCancellation: $controller})">Start Request</button>
    <button data-on:click="$controller.abort()">Cancel Request</button>
</div>
```

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

### Conditional Helpers in StarHTML

Source: https://context7.com/banditburai/starhtml/llms.txt

Use `match`, `switch`, `collect`, `.if_()`, and `.one_of()` for dynamic UI logic based on signal values. Ensure signals are properly initialized before use.

```python
from starhtml import *

app, rt = star_app()

@rt("/")
def home():
    return Div(
        (status := Signal("status", "pending")),
        (theme := Signal("theme", "light")),
        (is_admin := Signal("is_admin", False)),
        (is_verified := Signal("is_verified", True)),

        # match() - Value-based mapping (like switch/case)
        Span(data_text=match(status,
            pending="Waiting...",
            approved="Approved",
            rejected="Rejected",
            default="Unknown"
        )),

        # match() with CSS classes
        Div(
            "Status Badge",
            data_attr_class=match(status,
                pending="bg-yellow-100 text-yellow-800",
                approved="bg-green-100 text-green-800",
                rejected="bg-red-100 text-red-800",
                default="bg-gray-100"
            ),
        ),

        # switch() - Sequential conditions (if/elif/else)
        Span(data_text=switch([
            (~name, "Name is required"),
            (name.length < 2, "Name too short"),
            (~email.contains("@"), "Invalid email"),
        ], default="Valid")),

        # collect() - Combine multiple true conditions (for CSS classes)
        Div(
            "User Badge",
            data_attr_class=collect([
                (True, "badge"),  # Always included
                (is_admin, "badge-admin"),
                (is_verified, "badge-verified"),
            ]),
        ),

        # .if_() - Simple true/false ternary
        Span(data_text=is_admin.if_("Admin", "User")),

        # .one_of() - Constrain to allowed values
        Div(data_attr_class=theme.one_of("light", "dark", default="light")),
    )

```

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

### Register Startup and Shutdown Handlers (Decorator)

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Register startup and shutdown handlers using decorators after creating the app instance. This method is useful for adding event handlers to an existing application object.

```python
@app.on_event("startup")
async def init_db():
    ...

@app.on_event("shutdown")
def cleanup():
    ...
```

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

### Basic StarHTML App with Reactive Counter

Source: https://github.com/banditburai/starhtml/blob/main/README.md

A simple StarHTML application demonstrating reactive state management with signals and server-side interactions. Requires running the app with `python app.py` and visiting `http://localhost:5001`.

```python
from starhtml import *

app, rt = star_app()

@rt('/')
def home():
    return Div(
        H1("StarHTML Demo"),

        # Define reactive state with signals
        Div(
            (counter := Signal("counter", 0)),  # Python-first signal definition

            # Reactive UI that updates automatically
            P("Count: ", Span(data_text=counter)),
            Button("+", data_on_click=counter.add(1)),
            Button("Reset", data_on_click=counter.set(0)),

            # Conditional styling
            data_class_active=counter > 0
        ),

        # Server-side interactions
        Button("Load Data", data_on_click=get("/api/data")),
        Div(id="content")
    )

@rt('/api/data')
def api_data():
    return Div("Data loaded from server!", id="content")

serve()
```

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

### CSS: Placeholder Contrast

Source: https://github.com/banditburai/starhtml/blob/main/docs/plans/2026-02-15-debugger-phase-1.5.md

Set the color and opacity for input placeholders to ensure sufficient contrast.

```css
.toolbar input::placeholder { color: #585b70; opacity: 1; }
```

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

### Full Trace HTML Rendering

Source: https://github.com/banditburai/starhtml/blob/main/docs/plans/2026-02-17-debugger-timeline-tab.md

Implements `buildFullTraceHtml` to render a flat, timestamped event dump in a `<pre>` block. Includes a copy button for easy data extraction.

```typescript
Implement `buildFullTraceHtml(traceId): string` — flat timestamped event dump in `<pre>` block with copy button.
```

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

### Run Tests with Coverage

Source: https://github.com/banditburai/starhtml/blob/main/tests/unit/README.md

Execute all unit tests and generate an HTML coverage report for the starhtml module. This helps identify areas with missing test coverage.

```bash
uv run pytest tests/unit/ --cov=starhtml --cov-report=html
```

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

### Run Specific Pytest Class

Source: https://github.com/banditburai/starhtml/blob/main/tests/README.md

Execute tests belonging to a specific class within a test file, for example, 'TestEventHandling' in 'test_handlers.py', using 'uv run pytest' with the class name appended after '::' and the '-v' flag.

```bash
uv run pytest tests/unit/test_handlers.py::TestEventHandling -v
```

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

### Patch 2: Outside Modifier Race Fix (Same-event)

Source: https://github.com/banditburai/starhtml/blob/main/patches/README.md

Registers a capture-phase listener to snapshot an element's visibility state at the start of an event. This prevents the outside handler from incorrectly closing elements that were hidden when the event began.

```javascript
document.addEventListener(eventType, handler, true); // true for capture phase

// ... inside capture handler

const isHidden = element.style.display === "none";
if (isHidden) {
  // suppress outside event
}
```

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

### Run Specific Test File

Source: https://github.com/banditburai/starhtml/blob/main/tests/unit/README.md

Execute unit tests from a particular file, such as test_datastar_attrs.py. Use the -v flag for verbose output.

```bash
uv run pytest tests/unit/test_datastar_attrs.py -v
```

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

### Filter Elements by Attribute Name Prefix

Source: https://github.com/banditburai/starhtml/blob/main/tests/browser/test_attribute_selector.html

This approach manually queries all elements and then filters them using JavaScript to find elements whose attribute names start with a specific prefix. This is useful when standard CSS selectors are insufficient or for more complex attribute matching.

```javascript
const allElements = document.querySelectorAll('*');
const resizeElements = Array.from(allElements).filter(el => Array.from(el.attributes).some(attr => attr.name.startsWith('data-on-resize')) );
console.log('Elements with data-on-resize* attributes:', resizeElements.length);
```

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

### Client-Side HTTP Actions with StarHTML

Source: https://context7.com/banditburai/starhtml/llms.txt

Generate Datastar action expressions for making HTTP requests from the browser. Supports basic methods (GET, POST, PUT, DELETE) and advanced options like dynamic URLs, custom content types, conditional requests, and custom payloads.

```python
from starhtml import *

app, rt = star_app()

@rt("/")
def home():
    return Div(
        (item_id := Signal("item_id", 1)),

        # Basic HTTP actions
        Button("Fetch", data_on_click=get("/api/data")),
        Button("Save", data_on_click=post("/api/save")),
        Button("Update", data_on_click=put("/api/update")),
        Button("Delete", data_on_click=delete("/api/delete")),

        # Dynamic URL with Python variable
        Button("Load Item", data_on_click=get(f"/api/items/{item_id._initial}")),

        # With options
        Button(
            "Submit Form",
            data_on_click=post("/api/submit", contentType="form"),
        ),

        # Conditional request
        Button(
            "Save if Valid",
            data_on_click=is_valid.then(post("/api/save")),
        ),

        # Custom payload (not all signals)
        Button(
            "Save Text",
            data_on_blur=post("/api/edit", payload={"text": js("evt.target.innerText.trim()")}),
        ),
    )
```

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

### SSE Best Practice: Preserving IDs on Element Replacement

Source: https://github.com/banditburai/starhtml/blob/main/API.md

When replacing elements using SSE, it's crucial to preserve the `id` of the target element. This ensures that subsequent selectors continue to work correctly for future updates. The example shows how to replace content while maintaining the element's ID.

```python
# yield elements(
#     Div("New content", id="messages", cls="messages-container"),
#     "#messages"  # Replacement still has id="messages"
# )
```

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

### Activate StarHTML Debugger with serve()

Source: https://github.com/banditburai/starhtml/blob/main/docs/designs/2026-02-15-starhtml-debugger.md

When `debug=True` is passed to `serve()`, the StarHTML Debugger is automatically registered and injected into the page. Set `debug=False` (default) for zero overhead.

```python
app.serve(debug=True)
```

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

### Client-side WebSocket with Datastar

Source: https://context7.com/banditburai/starhtml/llms.txt

Establishes a WebSocket connection and handles incoming messages to update the DOM. Input is sent as JSON upon pressing Enter.

```python
from starhtml import *
from starhtml.core.signals import Signal

@rt("/")
def home():
    return Div(
        Script("""
            const ws = new WebSocket(`ws://${location.host}/chat`);
            ws.onmessage = (e) => document.getElementById('output').innerHTML = e.data;
        """),
        Input(id="input", onkeyup="if(event.key==='Enter')ws.send(JSON.stringify({message:this.value}))"),
        Div(id="output"),
    )
```

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

### Live Chat with Server-Sent Events

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Implement a real-time chat application using Server-Sent Events (SSE). This snippet demonstrates how to handle user input, send messages to the server, and receive updates in real-time.

```python
from starhtml import *
import time

def chat_app():
    message = Signal("message", "")
    sending = Signal("sending", False)

    return Div(
        message, sending,  # Signals render as hidden setup attributes
        
        H1("Live Chat"),
        
        # Messages container
        Div(id="messages", cls="messages-container"),
        
        # Chat input form
        Form(
            Input(
                placeholder="Type your message...",
                data_bind=message,           # Two-way bind to message signal
                data_attr_disabled=sending,   # Disable while sending
                cls="message-input"
            ),
            
            Button(
                data_text=sending.if_("Sending...", "Send"),
                type="submit",
                data_attr_disabled=sending | ~message,  # Disabled when sending or empty
                cls="send-button"
            ),
            
            # post() sends all current signal values to the server
            data_on_submit=(post("/chat/send"), {"prevent": True}),
            cls="chat-form"
        ),
        
        cls="chat-app"
    )

```

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

### Basic Datastar Signal Usage

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Declare a signal with an initial value and display it using a data attribute. The '$foo' signal is initialized to '1' and its value is rendered.

```html
<div data-signals:foo="1">
    <div data-text="$foo"></div>
</div>
```

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

### Create Element Reference (Key)

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Use `data-ref:key` to create a signal that references the element. The signal name is derived from the key.

```html
<div data-ref:foo></div>
```

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

### Update Datastar Version

Source: https://github.com/banditburai/starhtml/blob/main/patches/README.md

Use this command to update the Datastar version. The 'v' prefix is optional. This downloads vanilla Datastar, verifies patches, and updates the version tracking file.

```bash
python scripts/update_datastar.py 1.0.0-RC.8
bun run build
```

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

### Initialize StarHTML with Debug Parameter

Source: https://github.com/banditburai/starhtml/blob/main/docs/plans/2026-02-15-starhtml-debugger.md

Configure the debug parameter in StarHTML's initialization, with support for overriding via the STARHTML_DEBUG environment variable. A warning is printed to stderr when debug mode is enabled.

```python
self.debug = debug
env_debug = os.environ.get("STARHTML_DEBUG")
if env_debug is not None:
    self.debug = env_debug in ("1", "true", "yes")

if self.debug:
    print("WARNING: StarHTML debug mode is ON. Do not use in production.", file=sys.stderr)
```

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

### Performance Comparison of Selection Methods

Source: https://github.com/banditburai/starhtml/blob/main/tests/browser/test_attribute_selector.html

Compares the performance of selecting all elements ('*') versus selecting common HTML tags using querySelectorAll within a loop. This helps in understanding the performance implications of broad versus targeted selections.

```javascript
console.time('querySelectorAll(\* )');
for (let i = 0; i < 100; i++) {
  document.querySelectorAll('*');
}
console.timeEnd('querySelectorAll(\* )');
console.time('querySelectorAll(common tags)');
for (let i = 0; i < 100; i++) {
  document.querySelectorAll(commonTags);
}
console.timeEnd('querySelectorAll(common tags)');
```

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

### Implement Debug Parameter in StarHTML.__init__

Source: https://github.com/banditburai/starhtml/blob/main/docs/plans/2026-02-15-starhtml-debugger.md

This code snippet shows the necessary modification to the StarHTML class constructor to accept and process the 'debug' parameter.

```python
import os, sys

# In src/starhtml/core.py, add 'debug' parameter to StarHTML.__init__()
```

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

### Icon Sizing Options

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Illustrates various ways to control the size of icons, including explicit pixel/rem values, separate width/height, and Tailwind CSS size classes. Defaults to 1em if no size is specified.

```python
# Explicit size (applied to both width and height)
Icon("lucide:home", size=24)           # 24px
Icon("lucide:home", size="1.5rem")     # 1.5rem

# Separate width/height
Icon("lucide:home", width=32, height=24)

# Tailwind size classes (extracted automatically)
Icon("lucide:home", cls="size-6")      # 1.5rem from Tailwind mapping
Icon("lucide:home", cls="w-8 h-8")    # 2rem
Icon("lucide:home", cls="size-[2rem]") # Arbitrary value

# No size specified → defaults to 1em (inherits from font size)
Icon("lucide:home")
```

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

### star_app - Application Factory

Source: https://context7.com/banditburai/starhtml/llms.txt

Creates a StarHTML application instance. It supports various configurations including database integration, session management, middleware, and development tools like live reload.

```APIDOC
## star_app - Application Factory

Creates a StarHTML application instance with routing, sessions, middleware, and optional database integration. Returns a tuple of the app and a route decorator.

### Parameters

- **db_file** (str) - Optional - Path to the SQLite database file.
- **items** (dict) - Optional - Defines database table schema for ORM.
- **title** (str) - Optional - Title for the application.
- **debug** (bool) - Optional - Enables debug mode.
- **devtools** (bool) - Optional - Enables developer tools.
- **live** (bool) - Optional - Enables live reload.
- **hdrs** (list) - Optional - List of HTML headers to include.
- **secret_key** (str) - Optional - Secret key for session encryption.
- **session_cookie** (str) - Optional - Name of the session cookie.
- **max_age** (int) - Optional - Maximum age of the session cookie in seconds.
- **middleware** (list) - Optional - List of middleware functions to apply.
- **on_startup** (list) - Optional - List of functions to run on application startup.
- **on_shutdown** (list) - Optional - List of functions to run on application shutdown.
- **inline_icons** (bool) - Optional - Enables inline SVG icon rendering.

### Request Example

```python
from starhtml import *

# Basic app creation
app, rt = star_app()

# With database integration (SQLite via fastlite)
app, rt, items, Item = star_app(
    db_file="data.db",
    items=dict(id=int, title=str, done=bool),
    title="Todo App",
    debug=True,
    devtools=True,
    live=True,  # Enable live reload
    hdrs=[Script(src="https://cdn.tailwindcss.com")],
)

# With custom session and middleware
app, rt = star_app(
    secret_key="my-secret-key",
    session_cookie="my_session",
    max_age=7 * 24 * 3600,  # 7 days
    middleware=[compression()],  # Built-in gzip/brotli
    on_startup=[init_database],
    on_shutdown=[close_database],
    inline_icons=True,  # Server-side SVG rendering
)
```
```

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

### Backend Actions

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

Directives for making HTTP requests to the backend.

```APIDOC
## @get()

### Description
Sends a `GET` request using the Fetch API. The response should contain Datastar SSE events.

### Method
GET

### Endpoint
`/endpoint`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```html
<button data-on:click="@get('/endpoint')"></button>
<button data-on:click="@get('/endpoint', {openWhenHidden: true})"></button>
<button data-on:click="@get('/endpoint', {contentType: 'form'})></button>
```

### Response
N/A (Handles SSE, HTML, JSON, JavaScript)

## @post(), @put(), @patch(), @delete()

### Description
These actions send `POST`, `PUT`, `PATCH`, or `DELETE` requests respectively. Signals are sent as a JSON body.

### Method
POST, PUT, PATCH, DELETE

### Endpoint
`/endpoint`

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A (Signals are sent as JSON body by default)

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

### Response
N/A (Handles SSE, HTML, JSON, JavaScript)

## Options

### Description
Options available for backend actions.

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Options List
- **contentType**: `'json'` or `'form'`. Defaults to `'json'`.
- **filterSignals**: An object `{include: RegExp, exclude: RegExp}` to filter signals sent with the request.
- **selector**: A CSS selector for a form when `contentType` is `'form'`.
- **headers**: An object of custom headers.
- **openWhenHidden**: `true` or `false`. Defaults to `false`.
- **retryInterval**, **retryScaler**, **retryMaxWaitMs**, **retryMaxCount**: Control retry behavior.
- **requestCancellation**: `'auto'`, `'disabled'`, or an `AbortController`. Defaults to `'auto'`.

### Request Example
```html
<!-- Allow concurrent requests -->
<button data-on:click="@get('/endpoint', {requestCancellation: 'disabled'})">Allow Multiple</button>

<!-- Custom abort controller -->
<div data-signals:controller="new AbortController()">
    <button data-on:click="@get('/endpoint', {requestCancellation: $controller})">Start Request</button>
    <button data-on:click="$controller.abort()">Cancel Request</button>
</div>
```

### Response
N/A

## Response Handling

### Description
Backend actions handle different response `content-type` values.

### Response Types
- `text/event-stream`: Standard SSE with Datastar events.
- `text/html`: HTML to patch into the DOM. Can use `datastar-selector`, `datastar-mode`, and `datastar-use-view-transition` headers.
- `application/json`: JSON signals to patch. Can use `datastar-only-if-missing` header.
- `text/javascript`: JavaScript to execute. Can use `datastar-script-attributes` header.
```

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

### Python Comparison and Math Operators to JavaScript

Source: https://github.com/banditburai/starhtml/blob/main/API.md

Demonstrates the direct translation of common Python comparison (`>=`, `==`) and math (`*`, `/`) operators into their JavaScript counterparts for use in reactive expressions.

```python
age >= 18                    # → $age >= 18
count == 0                   # → $count === 0
price * quantity             # → $price * $quantity
(current / total) * 100      # → ($current / $total) * 100
```

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

### StarHTML Debugger Demo Page

Source: https://github.com/banditburai/starhtml/blob/main/docs/plans/2026-02-15-starhtml-debugger.md

A demo page for the StarHTML debugger, demonstrating its features including SSE events and dynamic content updates. It requires `star_app`, `sse`, and `signals` from `starhtml`.

```python
from starhtml.starapp import star_app
from starhtml.datastar import *

app, rt = star_app(debug=True)

count = Signal("count", 0)

@rt("/")
def home():
    return Div(
        H1("Debugger Demo"),
        P("Open the debug panel with Ctrl/Cmd+Shift+. or click the tab at the bottom."),
        Div(
            Button("Increment", data_on_click=sse("/increment")),
            Button("Add Element", data_on_click=sse("/add-element")),
            Span(data_text=count, id="counter"),
        ),
        Div(id="dynamic-content"),
    )

@rt("/increment")
async def increment(request):
    from starhtml.realtime import sse, signals
    @sse(request)
    async def stream():
        yield signals(count=count + 1)
    return stream

@rt("/add-element")
async def add_element(request):
    from starhtml.realtime import sse, elements
    @sse(request)
    async def stream():
        yield elements(
            P("New paragraph added!", cls="text-green-500"),
            selector="#dynamic-content",
            mode="append",
        )
    return stream

from starhtml.server import serve
serve(port=5030)
```

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

### SSE Event Handling for Quiz Application

Source: https://github.com/banditburai/starhtml/blob/main/DATASTAR_REFERENCE.md

This snippet shows how to handle Server-Sent Events (SSE) for a quiz. It fetches a question, allows user input, and displays feedback based on whether the answer is correct. State is driven from the backend.

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