STX API Reference

A comprehensive reference for all STX templating syntax, directives, and APIs.

Table of Contents

• Single File Components (SFC)
• Script Types
• Template Expressions
• Components
• Props & Slots
• Layouts & Sections
• Directives
  • Conditionals
  • Loops
  • Auth Guards
  • Environment
  • Includes & Partials
  • Stack & Push
  • Forms
  • SEO
• Prefix Convention
• Event Handling
• Icons
• Custom Directives
• Configuration
• State Management
• Lifecycle Hooks
• Refs (DOM References)
• Transitions
• Deferred Loading (@defer)
• Teleport (@teleport)
• Browser Composables
• Navigation API
• Event Listener Composable
• Meta Tag Management
• Timer Composables
• Utility Composables
• Color Mode
• Strict Mode
• Auto-Imported APIs Summary
• Form Validation
• Head Management
• Static Site Generation (SSG)
• Visual Testing
• Hydration Runtime
• Component HMR
• Deployment
• Image Optimization
• Suggested Future Syntax
• v2 Features
  • Signals vs Alpine-Style Reactivity
  • TypeScript-First Scripts
  • Auto-Binding
  • Scoped Styles
  • App Shell
  • Client-Side Router Hydration
  • StxLink Component
  • Component Composition API

Single File Components (SFC)

STX uses Vue-like Single File Components with <script>, <template>, and <style> sections. TypeScript is the default — all <script> blocks are transpiled via Bun.Transpiler automatically. No lang="ts" attribute needed.

<!-- components/MyComponent.stx -->
<script server>
// Server-side only - extracted for SSR, stripped from output
const title: string = props.title || 'Default Title'
const count: number = props.count || 0
</script>

<template>
  <div class="card">
    <h1>{{ title }}</h1>
    <p>Count: {{ count }}</p>
    <slot />
  </div>
</template>

<style scoped>
.card {
  padding: 1rem;
  border: 1px solid #ccc;
}
</style>

<script client>
// Client-side only - TypeScript works here too
interface User { name: string; role: string }

const user: User = { name: 'John', role: 'Admin' }
onMount(() => {
  console.log('Component mounted')
})
</script>

To opt out of TypeScript transpilation, use <script js> or <script lang="js">.

Script Types

Server Script

<script server>
// Runs during SSR, variables available in template
const user = await fetchUser()
const posts = await getPosts(user.id)
</script>

Client Script

<script client>
// Only runs in browser, never evaluated on server
// Auto-imports available: state, useRef, navigate, useQuery, etc.
onMount(() => {
  console.log('Page loaded')
})
</script>

Template Expressions

Escaped Output (Safe)

{{ variable }}
{{ user.name }}
{{ items.length }}
{{ formatDate(date) }}

Raw HTML Output (Unescaped)

{!! trustedHtml !!}
{!! markdown(content) !!}

Components

Components in components/ are auto-imported using PascalCase naming.

Usage

<!-- Auto-imported from components/UserCard.stx -->
<UserCard name="John" role="Admin" />

<!-- With slot content -->
<Card title="Welcome">
  <p>This content goes into the slot!</p>
</Card>

<!-- Nested in folders: components/forms/Input.stx -->
<FormsInput type="email" />

Explicit Imports

@import('layouts/Sidebar')
@import('shared/Button', 'shared/Modal')

<Sidebar />
<Button label="Click me" />

Props & Slots

Passing Props

<!-- String prop -->
<Card title="Hello" />

<!-- Expression binding with : -->
<Card :count="items.length" :active="isActive" />

<!-- Mustache interpolation -->
<Card title="{{ userName }}" />

<!-- Boolean props -->
<Button disabled />
<Modal :visible="showModal" />

Accessing Props in Components

Simple props access

<script server>
// Via props object
const title = props.title || 'Default'
const count = props.count || 0

// Destructured (also works)
const { name, email } = props
</script>

<template>
  <h1>{{ title }}</h1>
  <p>{{ props.description }}</p>
</template>

Typed props with defineProps (v2)

<script>
interface CardProps {
  title: string
  count?: number
  variant?: 'primary' | 'secondary'
}

const props = defineProps<CardProps>()
</script>

With defaults via withDefaults (v2)

<script>
const props = withDefaults(defineProps<{
  title: string
  variant?: string
  size?: string
}>(), {
  variant: 'primary',
  size: 'md',
})
</script>

With validation

<script>
const props = defineProps({
  title: { required: true },
  count: { default: 0 },
  status: {
    default: 'active',
    validator: (v) => ['active', 'inactive'].includes(v)
  }
})
</script>

Emitting Events (v2)

<script>
const emit = defineEmits<{
  change: string
  submit: { data: Record<string, unknown> }
}>()

function handleClick() {
  emit('change', 'new value')
}
</script>

Parent listens via CustomEvent:

<my-component @change="handleChange($event.detail)" />

Slots

<!-- Default slot -->
<template>
  <div class="wrapper">
    <slot />
  </div>
</template>

<!-- With default content -->
<template>
  <div class="wrapper">
    <slot>Default content if no slot provided</slot>
  </div>
</template>

Layouts & Sections

Defining a Layout

<!-- layouts/default.stx -->
<!DOCTYPE html>
<html>
<head>
  <title>{{ title || 'My App' }}</title>
</head>
<body>
  <Header />
  <main>
    @slot('content')
  </main>
  <Footer />
</body>
</html>

Using a Layout

<!-- pages/about.stx -->
@layout('default')

@section('content')
  <h1>About Us</h1>
  <p>Welcome to our site.</p>
@endsection

Multiple Slots

<!-- Layout -->
<head>
  @slot('head')
</head>
<body>
  @slot('content')
  @slot('scripts')
</body>

<!-- Page -->
@layout('default')

@section('head')
  <link rel="stylesheet" href="/custom.css">
@endsection

@section('content')
  <h1>Page Content</h1>
@endsection

@section('scripts')
  <script src="/custom.js"></script>
@endsection

Directives

Conditionals

@if / @elseif / @else

@if (user.isAdmin)
  <AdminPanel />
@elseif (user.isEditor)
  <EditorTools />
@else
  <UserView />
@endif

@unless

@unless (user.isGuest)
  <UserDashboard />
@endunless

@isset / @empty

@isset (user.avatar)
  <img src="{{ user.avatar }}" />
@endisset

@empty (notifications)
  <p>No notifications</p>
@endempty

Loops

@foreach

@foreach (items as item)
  <li>{{ item.name }}</li>
@endforeach

<!-- With index -->
@foreach (items as item, index)
  <li>{{ index }}: {{ item.name }}</li>
@endforeach

<!-- With key-value -->
@foreach (object as key, value)
  <dt>{{ key }}</dt>
  <dd>{{ value }}</dd>
@endforeach

@for

@for (let i = 0; i < 5; i++)
  <li>Item {{ i }}</li>
@endfor

@while

@while (condition)
  <p>Still true...</p>
@endwhile

@forelse

@forelse (users as user)
  <li>{{ user.name }}</li>
@empty
  <li>No users found</li>
@endforelse

Auth Guards

@auth
  <p>Welcome back, {{ user.name }}!</p>
  <LogoutButton />
@endauth

@guest
  <a href="/login">Please log in</a>
@endguest

<!-- With specific guard -->
@auth('admin')
  <AdminControls />
@endauth

Environment

@env('production')
  <Analytics />
@endenv

@env('local', 'development')
  <DebugBar />
@endenv

Includes & Partials

<!-- Basic include -->
@include('partials/header')

<!-- With data -->
@include('partials/user-card', { user: currentUser, showAvatar: true })

<!-- Conditional include -->
@includeIf('partials/optional')

<!-- Include when condition is true -->
@includeWhen(user.isAdmin, 'partials/admin-tools')

<!-- Include first existing -->
@includeFirst(['custom/header', 'default/header'])

Stack & Push

<!-- In layout: define a stack -->
@stack('scripts')
@stack('styles')

<!-- In components/pages: push to stack -->
@push('scripts')
  <script src="/component-specific.js"></script>
@endpush

@push('styles')
  <link rel="stylesheet" href="/component.css">
@endpush

<!-- Prepend to stack -->
@prepend('scripts')
  <script src="/load-first.js"></script>
@endprepend

@once

<!-- Only renders once even if component is used multiple times -->
@once
  <script src="/shared-library.js"></script>
@endonce

Forms

<form method="POST">
  @csrf
  <!-- Generates: <input type="hidden" name="_token" value="..."> -->
</form>

@method

<form method="POST">
  @method('PUT')
  <!-- Generates: <input type="hidden" name="_method" value="PUT"> -->
</form>

@error

<input name="email" type="email">
@error('email')
  <span class="error">{{ message }}</span>
@enderror

SEO

@meta('description', 'Page description here')
@meta('keywords', 'stx, templating, framework')
@meta('author', post.author)            <!-- unquoted: an expression -->

@seo({
  title: 'Page Title',
  description: 'Page description',
  openGraph: { image: '/og-image.jpg', type: 'article' }
})

@seo(seo)                                <!-- any expression that evaluates to an object -->
@structuredData(product)

Arguments are expressions evaluated against the template's context; a quoted string is literal text. A directive that cannot produce its tag (a variable that is not defined, a value of the wrong type) leaves an HTML comment in its place and logs a [stx] warning naming the file. See the directives reference.

Prefix Convention

stx uses three prefixes to clearly separate concerns:

Structural Directives (: prefix)

<div :if="isLoggedIn">Welcome back</div>
<div :show="menuOpen">Menu content</div>
<div :for="item in items" :key="item.id">{{ item.name }}</div>

Attribute Bindings (x- prefix)

<!-- Dynamic attributes -->
<a x-href="'/user/' + userId">Profile</a>
<img x-src="user.avatar" x-alt="user.name" />

<!-- Dynamic classes and styles -->
<div x-class="isActive ? 'bg-green-500' : 'bg-gray-200'">Status</div>
<div x-style="'color: ' + themeColor">Themed</div>

<!-- Content -->
<span x-text="userName"></span>
<div x-html="richContent"></div>

<!-- Form binding -->
<input x-model="email" type="email" placeholder="Email">

Events (@ prefix)

<button @click="handleClick()">Click me</button>
<button @click="count.set(count() + 1)">Increment</button>
<form @submit.prevent="submitForm()">...</form>
<input @keydown.enter="search()">

Reactivity

All client-side state lives in <script client> blocks using signals. x-data is deprecated — state belongs in TypeScript, not inline HTML attributes.

<script client>
  const count = state(0)
  const email = state('')
  const doubled = derived(() => count() * 2)
</script>

<span x-text="count()"></span>
<button @click="count.set(count() + 1)">+1</button>
<p>Doubled: <span x-text="doubled()"></span></p>

<input x-model="email" type="email">
<p>Email: <span x-text="email()"></span></p>

x-model

Two-way binding for form inputs:

<script client>
  const email = state('')
  const password = state('')
</script>

<input x-model="email" type="email" placeholder="Email">
<input x-model="password" type="password" placeholder="Password">
<p>Email: <span x-text="email()"></span></p>

x-text

Reactive text content:

<script client>
  const count = state(0)
</script>

<span x-text="count()"></span>
<button @click="count.set(count() + 1)">Increment</button>

Event Handling

@click

<button @click="handleClick()">Click me</button>
<button @click="count++">Increment</button>
<button @click="visible = !visible">Toggle</button>

Other Events

<input @input="handleInput($event)">
<input @change="handleChange($event)">
<form @submit="handleSubmit($event)">
<div @mouseover="isHovered = true" @mouseout="isHovered = false">

Event Modifiers

<!-- Prevent default -->
<form @submit.prevent="handleSubmit()">

<!-- Stop propagation -->
<button @click.stop="handleClick()">

<!-- Once only -->
<button @click.once="initOnce()">

<!-- Key modifiers -->
<input @keyup.enter="submit()">
<input @keyup.escape="cancel()">

Icons

STX integrates with Iconify for 200K+ icons.

Usage

<HomeIcon size="24" />
<SearchIcon size="20" color="#333" />
<UserIcon size="32" class="text-blue-500" />

CLI Commands

# List available icon collections
stx iconify list

# Generate icon package for a collection
stx iconify generate material-symbols
stx iconify generate heroicons

Custom Directives

Registering Custom Directives

import { stxPlugin, type CustomDirective } from 'bun-plugin-stx'

// Simple directive
const uppercase: CustomDirective = {
  name: 'uppercase',
  handler: (content, params) => params[0]?.toUpperCase() || content.toUpperCase()
}

// Block directive with end tag
const wrap: CustomDirective = {
  name: 'wrap',
  hasEndTag: true,
  handler: (content, params) => `<div class="${params[0] || 'wrapper'}">${content}</div>`
}

// Async directive
const fetch: CustomDirective = {
  name: 'fetch',
  async: true,
  handler: async (content, params) => {
    const response = await fetch(params[0])
    return await response.text()
  }
}

Bun.build({
  entrypoints: ['./src/index.stx'],
  plugins: [stxPlugin({
    customDirectives: [uppercase, wrap, fetch]
  })]
})

Using Custom Directives

<!-- Inline directive -->
<p>@uppercase('hello world')</p>
<!-- Output: HELLO WORLD -->

<!-- Block directive -->
@wrap('container')
  <p>Wrapped content</p>
@endwrap
<!-- Output: <div class="container"><p>Wrapped content</p></div> -->

Configuration

stx.config.ts

import type { StxConfig } from '@stacksjs/stx'

const config: StxConfig = {
  // Directory configuration
  pagesDir: 'pages',
  componentsDir: 'components',
  layoutsDir: 'layouts',
  partialsDir: 'partials',
  publicDir: 'public',

  // Default layout for pages
  defaultLayout: 'default',

  // Caching
  cache: process.env.NODE_ENV === 'production',
  cachePath: '.stx/cache',

  // Debug mode
  debug: process.env.NODE_ENV !== 'production',

  // Accessibility
  a11y: {
    enabled: true,
    level: 'AA', // 'A', 'AA', or 'AAA'
  },

  // SEO
  seo: {
    enabled: true,
    socialPreview: true,
    defaultConfig: {
      title: 'My App',
      description: 'App description',
    },
  },

  // Internationalization
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    directory: 'locales',
  },

  // Custom directives
  customDirectives: [],

  // Middleware
  middleware: {
    before: [],
    after: [],
  },
}

export default config

State Management

STX provides a clean, Pinia-inspired state management system with reactive stores.

Defining Stores

Create stores in a dedicated file (e.g., stores/index.ts):

// stores/index.ts
import { defineStore, registerStoresClient } from 'stx'

// Define a store with state, getters, and actions
export const counterStore = defineStore('counter', {
  state: {
    count: 0,
    name: 'My Counter'
  },

  getters: {
    doubleCount: (state) => state.count * 2,
    displayName: (state) => `${state.name}: ${state.count}`
  },

  actions: {
    increment() {
      this.count++
    },
    decrement() {
      this.count--
    },
    incrementBy(amount: number) {
      this.count += amount
    },
    async fetchCount() {
      const response = await fetch('/api/count')
      this.count = await response.json()
    }
  },

  // Optional: persist to localStorage
  persist: true
})

export const appStore = defineStore('app', {
  state: {
    isLoading: false,
    user: null as { name: string; email: string } | null,
    theme: 'dark'
  },

  getters: {
    isAuthenticated: (state) => state.user !== null
  },

  actions: {
    setUser(user: { name: string; email: string } | null) {
      this.user = user
    },
    toggleTheme() {
      this.theme = this.theme === 'dark' ? 'light' : 'dark'
    }
  },

  persist: {
    storage: 'local',
    key: 'my-app-state'
  }
})

// Register stores for client-side @stores imports
if (typeof window !== 'undefined') {
  registerStoresClient({ counterStore, appStore })
}

Using Stores in Components

Import stores using the clean @stores syntax:

<script client>
import { counterStore, appStore } from '@stores'

// Access state directly
console.log(counterStore.count)        // 0
console.log(appStore.theme)            // 'dark'

// Use getters
console.log(counterStore.doubleCount)  // 0
console.log(appStore.isAuthenticated)  // false

// Call actions
counterStore.increment()
counterStore.incrementBy(5)
appStore.toggleTheme()

// Direct state mutation
counterStore.count = 10
appStore.theme = 'light'

// Subscribe to changes
counterStore.$subscribe((state, prevState) => {
  console.log('Count changed:', prevState?.count, '->', state.count)
})

// Patch multiple values at once
appStore.$patch({
  isLoading: true,
  theme: 'dark'
})

// Or with a function
appStore.$patch((state) => {
  state.isLoading = false
  state.user = { name: 'John', email: 'john@example.com' }
})

// Reset to initial state
counterStore.$reset()
</script>

<template>
  <div>
    <p>Count: {{ counterStore.count }}</p>
    <p>Double: {{ counterStore.doubleCount }}</p>
    <button @click="counterStore.increment()">+</button>
    <button @click="counterStore.decrement()">-</button>
  </div>
</template>

Store API Reference

Persistence Options

// Simple persistence (localStorage with auto key)
persist: true

// Custom persistence
persist: {
  storage: 'local',     // 'local' | 'session' | 'memory'
  key: 'my-custom-key'  // Custom storage key
}

Loading Stores in HTML

Include your stores before other scripts:

<!DOCTYPE html>
<html>
<head>
  <!-- Load store runtime -->
  <script src="/js/stores.js"></script>
</head>
<body>
  <!-- Your app content -->
  <script client>
  import { appStore } from '@stores'
  // Stores are immediately available
  console.log(appStore.theme)
  </script>
</body>
</html>

Waiting for Stores

If you need to ensure a store is loaded:

<script client>
import { waitForStore } from 'stx'

// Wait for store with timeout
const appStore = await waitForStore('app', 5000)
console.log(appStore.theme)
</script>

TypeScript Support

Stores are fully typed:

import { defineStore } from 'stx'

interface User {
  id: number
  name: string
  email: string
}

interface AppState {
  user: User | null
  isLoading: boolean
  errors: string[]
}

export const appStore = defineStore('app', {
  state: {
    user: null,
    isLoading: false,
    errors: []
  } as AppState,

  getters: {
    isAuthenticated: (state): boolean => state.user !== null,
    errorCount: (state): number => state.errors.length
  },

  actions: {
    async login(email: string, password: string): Promise<void> {
      this.isLoading = true
      try {
        const response = await fetch('/api/login', {
          method: 'POST',
          body: JSON.stringify({ email, password })
        })
        this.user = await response.json()
      } catch (e) {
        this.errors.push('Login failed')
      } finally {
        this.isLoading = false
      }
    },

    logout(): void {
      this.user = null
    }
  }
})

Lifecycle Hooks

Vue-inspired lifecycle hooks for managing component setup, cleanup, and updates.

onMount

Called when the component is mounted to the DOM. Perfect for setup, event listeners, and subscriptions.

<script client>
// onMount is auto-imported — no import needed

onMount(() => {
  console.log('Component mounted!')

  // Use useEventListener for auto-cleanup (preferred over raw addEventListener)
  const { remove } = useEventListener('click', () => console.log('clicked'))

  // Return cleanup function (called on unmount)
  return () => {
    remove()
  }
})
</script>

onDestroy

Called when the component is removed from the DOM. Use for cleanup.

<script client>
import { onMount, onDestroy } from 'stx'

onMount(() => {
  const interval = setInterval(() => {
    console.log('tick')
  }, 1000)

  // Can also register cleanup in onMount's return
  onDestroy(() => {
    clearInterval(interval)
  })
})
</script>

onUpdate

Called when the component updates (re-renders).

<script client>
import { onUpdate } from 'stx'

onUpdate(() => {
  console.log('Component updated!')
})
</script>

Aliases

Full Example

<script client>
import { onMount, onDestroy, onUpdate } from 'stx'
import { appStore } from '@stores'

onMount(() => {
  console.log('Chat component mounted')

  // Subscribe to store
  const unsubscribe = appStore.$subscribe((state) => {
    console.log('App state changed:', state)
  })

  // WebSocket connection
  const ws = new WebSocket('wss://api.example.com/chat')
  ws.onmessage = (e) => handleMessage(JSON.parse(e.data))

  // Cleanup
  return () => {
    unsubscribe()
    ws.close()
  }
})

onUpdate(() => {
  // Scroll to bottom when new messages arrive
  const messages = useRef('messages')
  messages.current?.scrollTo(0, messages.current.scrollHeight)
})
</script>

Refs (DOM References)

Direct references to DOM elements, similar to Vue's ref or React's useRef.

useRef() (Recommended)

The useRef() composable is the preferred way to reference DOM elements. It is auto-imported — no import statement needed.

<template>
  <input type="text" ref="myInput" placeholder="Auto-focused" />
  <button @click="myInput.current?.select()">Select All</button>
</template>

<script client>
// useRef is auto-imported — no import needed
const myInput = useRef('myInput')

onMount(() => {
  myInput.current?.focus()
})
</script>

A ref reads three ways, all the same value: call it like every other stx accessor, or read .current / .value if the surrounding code is shaped that way. All three answer null until the element is bound.

const shell = useRef('shell')

shell() // → HTMLElement | null
shell.current // → the same
shell.value // → the same

// Safe inside an effect, which runs its body immediately:
effect(() => {
  if (shell())
    console.log(shell().dataset.flag)
})

Binding Refs

Use ref="name", @ref="name", or :ref="name" to bind elements:

<template>
  <!-- All three syntaxes work identically -->
  <input ref="emailRef" type="email" />
  <input @ref="passwordRef" type="password" />
  <div :ref="containerRef">...</div>
</template>

<script client>
const email = useRef('emailRef')
const password = useRef('passwordRef')
const container = useRef('containerRef')

onMount(() => {
  email.current?.focus()
})
</script>

Multiple Refs

<template>
  <form ref="formRef">
    <input ref="emailRef" type="email" />
    <input ref="passwordRef" type="password" />
    <button type="submit">Login</button>
  </form>
</template>

<script client>
const form = useRef('formRef')
const email = useRef('emailRef')
const password = useRef('passwordRef')

onMount(() => {
  form.current?.addEventListener('submit', (e) => {
    e.preventDefault()
    console.log('Email:', email.current?.value)
    console.log('Password:', password.current?.value)
  })
})
</script>

useRef API

Legacy ref() (Still Supported)

The Vue-style ref() function also works for creating refs:

<script client>
import { ref, onMount } from 'stx'
const inputRef = ref<HTMLInputElement>()
onMount(() => inputRef.value?.focus())
</script>

Transitions

CSS-based enter/leave transitions for elements, inspired by Vue's transition system.

Basic Usage

@transition(name: 'fade')
  @if (visible)
    <div class="modal">Modal Content</div>
  @endif
@endtransition

Transition Options

@transition(name: 'slide-up', duration: 500, mode: 'out-in')
  @if (currentTab === 'home')
    <HomeTab />
  @elseif (currentTab === 'settings')
    <SettingsTab />
  @endif
@endtransition

Attribute Syntax

For simpler cases, use the attribute syntax:

<div @transition.fade="isVisible">Fading content</div>
<div @transition.slide-up.500="isOpen">Sliding content</div>

CSS Classes

STX applies these CSS classes during transitions:

Enter Transition:

Leave Transition:

Built-in Transitions

STX includes these ready-to-use transitions:

/* Available transition names */
fade        /* Opacity fade */
slide-up    /* Slide from bottom */
slide-down  /* Slide from top */
slide-left  /* Slide from right */
slide-right /* Slide from left */
scale       /* Scale from 90% */
scale-up    /* Scale from 50% */
bounce      /* Bouncy scale */
flip        /* 3D flip */
zoom        /* Zoom from 0 */
collapse    /* Height collapse */

Custom Transition CSS

Define your own transitions:

/* Custom 'swing' transition */
.swing-enter-from,
.swing-leave-to {
  opacity: 0;
  transform: translateX(-100%) rotate(-30deg);
}

.swing-enter-active,
.swing-leave-active {
  transition: all 0.5s cubic-bezier(0.68, -0.55, 0.265, 1.55);
}

.swing-enter-to,
.swing-leave-from {
  opacity: 1;
  transform: translateX(0) rotate(0);
}

@transition(name: 'swing')
  @if (showMenu)
    <nav class="menu">...</nav>
  @endif
@endtransition

JavaScript Transition Hooks

For programmatic control:

<script client>
// Enter transition
STX.transition.enter(element, {
  name: 'fade',
  duration: 300
})

// Leave transition (returns Promise)
await STX.transition.leave(element, {
  name: 'slide-up',
  duration: 500
})

// Toggle with transition
STX.transition.toggle(element, isVisible, {
  name: 'scale'
})
</script>

Modal Example

<template>
  <button @click="showModal = true">Open Modal</button>

  @transition(name: 'fade')
    @if (showModal)
      <div class="modal-overlay" @click.self="showModal = false">
        @transition(name: 'scale')
          <div class="modal-content">
            <h2>Modal Title</h2>
            <p>Modal content goes here...</p>
            <button @click="showModal = false">Close</button>
          </div>
        @endtransition
      </div>
    @endif
  @endtransition
</template>

<style>
.modal-overlay {
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
}
.modal-content {
  background: white;
  padding: 2rem;
  border-radius: 8px;
  max-width: 500px;
}
</style>

Scoped Slots

Scoped slots allow parent components to receive data from child components via slot props.

Named Slots

Basic named slots for content distribution:

<!-- Card.stx (Child Component) -->
<div class="card">
  <header>
    <slot name="header">Default Header</slot>
  </header>
  <main>
    <slot />  <!-- Default slot -->
  </main>
  <footer>
    <slot name="footer" />
  </footer>
</div>

<!-- Parent Usage -->
<Card>
  <template #header>
    <h1>Custom Title</h1>
  </template>

  <p>This goes in the default slot</p>

  <template #footer>
    <button>Submit</button>
  </template>
</Card>

Scoped Slots with Props

Pass data from child to parent via slot props:

<!-- DataTable.stx (Child Component) -->
<script>
const items = props.items || []
</script>

<table>
  <tbody>
    @foreach (items as item, index)
      <tr>
        <slot name="row" :item="item" :index="index">
          <!-- Default content if no slot provided -->
          <td>{{ item }}</td>
        </slot>
      </tr>
    @endforeach
  </tbody>
</table>

<!-- Parent Usage -->
<DataTable :items="users">
  <template #row="{ item, index }">
    <td>{{ index + 1 }}</td>
    <td>{{ item.name }}</td>
    <td>{{ item.email }}</td>
    <td>
      <button @click="editUser(item.id)">Edit</button>
    </td>
  </template>
</DataTable>

Slot Syntax Variants

<!-- Hash syntax (recommended) -->
<template #header>...</template>
<template #row="{ item }">...</template>

<!-- v-slot syntax (Vue compatible) -->
<template v-slot:header>...</template>
<template v-slot:row="{ item }">...</template>

<!-- slot attribute (legacy) -->
<template slot="header">...</template>

Default Slot Content

Provide fallback content when no slot is provided:

<!-- Button.stx -->
<button class="btn">
  <slot>Click Me</slot>  <!-- "Click Me" is the default -->
</button>

<!-- Usage -->
<Button>Submit</Button>    <!-- Shows "Submit" -->
<Button />                 <!-- Shows "Click Me" -->

Provide/Inject (Dependency Injection)

Provide/Inject allows ancestor components to pass data to any descendant without prop drilling.

Basic Usage

<!-- Parent.stx -->
<script>
import { provide } from 'stx'

const theme = 'dark'
const user = { name: 'John', role: 'admin' }

// Provide values to all descendants
provide('theme', theme)
provide('user', user)
</script>

<div class="app">
  <Header />
  <Content />
  <Footer />
</div>

<!-- DeepNestedChild.stx (any descendant) -->
<script>
import { inject } from 'stx'

// Inject values from any ancestor
const theme = inject('theme')
const user = inject('user')
</script>

<div class="{{ theme === 'dark' ? 'bg-gray-900' : 'bg-white' }}">
  <p>Welcome, {{ user.name }}!</p>
</div>

Default Values

Provide fallback values when injection is not found:

<script>
import { inject } from 'stx'

// With default value
const theme = inject('theme', 'light')
const locale = inject('locale', 'en-US')
</script>