Directives

On this page 29

stx provides a powerful directive system for extending template functionality. This page covers all built-in directives and how to create custom directives in the stx ecosystem.

Built-in Directives

Conditional Directives

@if / v-if / :if / x-if are interchangeable syntax for the same conditional. A condition over server data evaluates once at render time; a condition that reads a signal (on a page that uses signals) is reactive and re-evaluates on change — the keyword you pick is just style. See Conditionals.

<!-- Basic conditionals -->
@if(user.isAuthenticated)
  <dashboard />
@elseif(user.isGuest)
  <welcome-message />
@else
  <login-form />
@endif

<!-- Authentication helpers -->
@auth
  <admin-panel />
@endauth

@guest
  <signup-banner />
@endguest

<!-- Unless directive -->
@unless(user.hasPermission('admin'))
  <access-denied />
@endunless

Loop Directives

<!-- Basic foreach -->
@foreach(items as item)
  <div class="item">&#123;&#123; item.name &#125;&#125;</div>
@endforeach

<!-- With index -->
@foreach(users as index => user)
  <tr class="&#123;&#123; index % 2 === 0 ? 'even' : 'odd' &#125;&#125;">
    <td>&#123;&#123; index + 1 &#125;&#125;</td>
    <td>&#123;&#123; user.name &#125;&#125;</td>
  </tr>
@endforeach

<!-- With empty state -->
@forelse(posts as post)
  <article>&#123;&#123; post.title &#125;&#125;</article>
@empty
  <p>No posts found.</p>
@endforelse

<!-- For range -->
@for(i = 1; i <= 10; i++)
  <div>Item &#123;&#123; i &#125;&#125;</div>
@endfor

<!-- While loop -->
@while(hasMore && page < maxPages)
  <load-more-button @click="loadMore" />
@endwhile

Template Directives

<!-- Include partials -->
@include('components.user-card', { user: currentUser })

<!-- Extend layouts -->
@extends('layouts.app')

@section('title', 'Home Page')

@section('content')
  <h1>Welcome!</h1>
@endsection

<!-- Push to stacks -->
@push('styles')
  <link rel="stylesheet" href="/css/home.css">
@endpush

@push('scripts')
  <script src="/js/home.js"></script>
@endpush

<!-- Yield sections -->
@yield('content', 'Default content')
@stack('scripts')

<!-- Include markdown files -->
@markdown-file('content.md')
@markdown-file('docs/intro.md', {userName: 'Alice', role: 'Admin'})

Response Directives

<!-- The HTTP status this render should answer with -->
@status(404)

<!-- Any expression the template can evaluate -->
@status(feature ? 200 : 404)

@status runs after the conditionals, so it belongs inside the branch that already knows the answer:

@if (!feature)
  @status(404)
  <h1>No feature by that name.</h1>
@else
  <h1>{{ feature.title }}</h1>
@endif

A @status in the branch that lost never fires, so the page that found its record answers 200 without having to say so. Without this, a dynamic route that cannot resolve its parameter renders a not-found body under a 200 — which tells a crawler, a cache and an uptime check that the URL is a real page.

An argument that is not an HTTP status (100–599) is ignored with a warning rather than failing a page that has already rendered. The last @status wins.

@status is evaluated where the template is rendered, so it is skipped — with a warning — when stx build precompiles a page, which happens once with no request. On precompiled pages use notFound() or setResponseStatus() in <script server>; those are re-run per request. See <script server> for both spellings.

Markdown Directives

<!-- Include markdown files with frontmatter support -->
@markdown-file('content.md')

<!-- Relative paths -->
@markdown-file('./docs/getting-started.md')
@markdown-file('../shared/readme.md')

<!-- With additional context -->
@markdown-file('template.md', {userName: 'Alice', role: 'Admin'})

<!-- Inline markdown -->
@markdown
# This is a heading

This is **bold** and this is *italic*.

\`\`\`javascript
const code = 'highlighted';
\`\`\`
@endmarkdown

Markdown File with Frontmatter:

---
title: "Getting Started"
author: "stx Team"
date: 2025-10-08
---

# {{ title }}

Written by {{ author }}

This guide will help you get started with stx.
Variables from frontmatter and template context are available!

Features:

YAML frontmatter parsing
Variable substitution with {{ variable }}
Server-side syntax highlighting with Shiki
Supports GitHub Flavored Markdown (GFM)
Automatic caching for performance

See Markdown API for detailed documentation.

Form Directives

<!-- Two-way binding -->
<input @model="username" type="text">
<input @model.number="age" type="number">
<input @model.trim="message" type="text">

<!-- Checkbox binding -->
<input @model="isChecked" type="checkbox">

<!-- Select binding -->
<select @model="selectedOption">
  @foreach(options as option)
    <option x-value="option.value">&#123;&#123; option.label &#125;&#125;</option>
  @endforeach
</select>

<!-- Multiple select -->
<select @model="selectedItems" multiple>
  @foreach(items as item)
    <option x-value="item.id">&#123;&#123; item.name &#125;&#125;</option>
  @endforeach
</select>

Event Directives

<!-- Basic event handling -->
<button @click="handleClick">Click me</button>
<input @input="handleInput" @blur="handleBlur">

<!-- Event modifiers -->
<form @submit.prevent="onSubmit">
<button @click.stop="stopPropagation">
<input @keyup.enter="search">
<div @click.once="initializeOnce">

<!-- Dynamic events -->
<button @[eventName]="handler">Dynamic Event</button>

<!-- Multiple events -->
<input
  @input="handleInput"
  @focus="handleFocus"
  @blur="handleBlur"
>

Attribute Directives

<!-- Dynamic attributes -->
<img x-src="imageUrl" x-alt="imageAlt">
<button x-disabled="isLoading" x-class="buttonClass">

<!-- Dynamic attribute names -->
<input :[attributeName]="attributeValue">

<!-- Class binding -->
<div x-class="{
  'active': isActive,
  'disabled': isDisabled,
  'large': size === 'large'
}">
</div>

<!-- Style binding -->
<div x-style="{
  color: textColor,
  fontSize: fontSize + 'px',
  backgroundColor: bgColor
}">
</div>

Custom Directives

Simple Custom Directive

// directives/focus.ts
export const focus = {
  mounted(el: HTMLElement, binding: any) {
    if (binding.value) {
      el.focus()
    }
  },

  updated(el: HTMLElement, binding: any) {
    if (binding.value) {
      el.focus()
    }
  }
}

// Register directive
app.directive('focus', focus)

Usage:

<input @focus="shouldFocus" type="text">

Advanced Custom Directive

// directives/lazy-load.ts
export const lazyLoad = {
  mounted(el: HTMLElement, binding: any) {
    const options = {
      threshold: 0.1,
      rootMargin: '50px',
      ...binding.value?.options
    }

    const observer = new IntersectionObserver((entries) => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          const img = entry.target as HTMLImageElement

          // Load the image
          if (binding.value?.src) {
            img.src = binding.value.src
          }

          // Add loaded class
          img.classList.add('loaded')

          // Execute callback
          if (binding.value?.onLoad) {
            binding.value.onLoad(img)
          }

          observer.unobserve(img)
        }
      })
    }, options)

    observer.observe(el)

    // Store observer for cleanup
    el._lazyObserver = observer
  },

  beforeUnmount(el: HTMLElement) {
    if (el._lazyObserver) {
      el._lazyObserver.disconnect()
    }
  }
}

Usage:

<img
  @lazy-load="{
    src: '/images/large-image.jpg',
    onLoad: handleImageLoad,
    options: { threshold: 0.2 }
  }"
  src="/images/placeholder.jpg"
  alt="Lazy loaded image"
>

Directive with Arguments

// directives/click-outside.ts
export const clickOutside = {
  mounted(el: HTMLElement, binding: any) {
    const handler = (event: Event) => {
      if (!el.contains(event.target as Node)) {
        binding.value(event)
      }
    }

    document.addEventListener('click', handler)
    el._clickOutsideHandler = handler
  },

  beforeUnmount(el: HTMLElement) {
    if (el._clickOutsideHandler) {
      document.removeEventListener('click', el._clickOutsideHandler)
    }
  }
}

Usage:

<div @click-outside="closeMenu" class="dropdown">
  <!-- Dropdown content -->
</div>

Parameterized Directive

// directives/tooltip.ts
export const tooltip = {
  mounted(el: HTMLElement, binding: any) {
    const tooltip = document.createElement('div')
    tooltip.className = 'tooltip'
    tooltip.textContent = binding.value
    tooltip.style.display = 'none'
    document.body.appendChild(tooltip)

    const showTooltip = (event: MouseEvent) => {
      tooltip.style.display = 'block'
      tooltip.style.left = event.pageX + 10 + 'px'
      tooltip.style.top = event.pageY + 10 + 'px'
    }

    const hideTooltip = () => {
      tooltip.style.display = 'none'
    }

    el.addEventListener('mouseenter', showTooltip)
    el.addEventListener('mouseleave', hideTooltip)

    el._tooltip = tooltip
    el._showTooltip = showTooltip
    el._hideTooltip = hideTooltip
  },

  updated(el: HTMLElement, binding: any) {
    if (el._tooltip) {
      el._tooltip.textContent = binding.value
    }
  },

  beforeUnmount(el: HTMLElement) {
    if (el._tooltip) {
      document.body.removeChild(el._tooltip)
    }
    if (el._showTooltip) {
      el.removeEventListener('mouseenter', el._showTooltip)
    }
    if (el._hideTooltip) {
      el.removeEventListener('mouseleave', el._hideTooltip)
    }
  }
}

Usage:

<button @tooltip="'This is a helpful tooltip'">
  Hover me
</button>

Directive Composition

Multiple Directives

<input
  @model="searchQuery"
  @focus="true"
  @click-outside="closeSearchResults"
  @debounce:300="performSearch"
  type="text"
>

Directive Inheritance

// Base directive
const baseValidation = {
  mounted(el: HTMLElement, binding: any) {
    // Common validation logic
  }
}

// Extended directive
const emailValidation = {
  ...baseValidation,
  mounted(el: HTMLElement, binding: any) {
    baseValidation.mounted(el, binding)
    // Email-specific validation
    el.addEventListener('input', validateEmail)
  }
}

Built-in Directive Modifiers

Event Modifiers

<!-- Prevent default -->
<form @submit.prevent="onSubmit">

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

<!-- Capture phase -->
<div @click.capture="handleCapture">

<!-- Once only -->
<button @click.once="initialize">

<!-- Passive listener -->
<div @scroll.passive="handleScroll">

<!-- Touch and wheel listeners are passive already; opt out to call preventDefault() -->
<div @touchstart="startSwipe">
<canvas @wheel.nonpassive="zoom">

<!-- Key modifiers -->
<input @keyup.enter="search">
<input @keyup.esc="clearSearch">
<input @keyup.ctrl.s="save">

@touchstart, @touchmove and @wheel listen passively by default, so a scroll that starts on the element never waits for the handler. .prevent keeps a blocking listener, since it calls preventDefault(); write .nonpassive when the handler calls it itself.

Model Modifiers

<!-- Trim whitespace -->
<input @model.trim="message">

<!-- Convert to number -->
<input @model.number="age">

<!-- Lazy sync (on change instead of input) -->
<input @model.lazy="value">

<!-- Debounced input -->
<input @model.debounce:500="searchQuery">

Async Directives

Async Directive Example

// directives/async-load.ts
export const asyncLoad = {
  async mounted(el: HTMLElement, binding: any) {
    el.classList.add('loading')

    try {
      const data = await binding.value()

      // Update element with loaded data
      if (typeof data === 'string') {
        el.textContent = data
      } else if (data.html) {
        el.innerHTML = data.html
      }

      el.classList.remove('loading')
      el.classList.add('loaded')
    } catch (error) {
      el.classList.remove('loading')
      el.classList.add('error')
      console.error('Async load failed:', error)
    }
  }
}

Usage:

<div @async-load="loadUserData">Loading...</div>

Directive Testing

Testing Custom Directives

import { mount } from '@stacksjs/testing'
import { tooltip } from './directives/tooltip'

describe('Tooltip Directive', () => {
  test('creates tooltip on hover', async () => {
    const wrapper = mount({
      template: '<button @tooltip="\'Test tooltip\'">Hover</button>',
      directives: { tooltip }
    })

    const button = wrapper.find('button')
    await button.trigger('mouseenter')

    const tooltipEl = document.querySelector('.tooltip')
    expect(tooltipEl).toBeTruthy()
    expect(tooltipEl.textContent).toBe('Test tooltip')

    await button.trigger('mouseleave')
    expect(tooltipEl.style.display).toBe('none')
  })
})

Integration Testing

describe('Form with Custom Directives', () => {
  test('validation and focus work together', async () => {
    const wrapper = mount({
      template: `
        <form>
          <input
            @model="email"
            @focus="true"
            @validate="validateEmail"
            type="email"
          >
        </form>
      `,
      data: {
        email: ''
      }
    })

    const input = wrapper.find('input')
    expect(document.activeElement).toBe(input.element)

    await input.setValue('invalid-email')
    // Test validation behavior
  })
})

Performance Considerations

Efficient Directive Updates

export const optimizedDirective = {
  mounted(el: HTMLElement, binding: any) {
    // Initialize once
    el._directiveData = {
      previousValue: binding.value,
      handler: createHandler(binding.value)
    }
  },

  updated(el: HTMLElement, binding: any) {
    // Only update if value changed
    if (binding.value !== el._directiveData.previousValue) {
      // Cleanup previous
      cleanup(el._directiveData.handler)

      // Setup new
      el._directiveData = {
        previousValue: binding.value,
        handler: createHandler(binding.value)
      }
    }
  }
}

Memory Management

export const memoryEfficientDirective = {
  mounted(el: HTMLElement, binding: any) {
    const controller = new AbortController()

    el.addEventListener('click', handler, {
      signal: controller.signal
    })

    // Store for cleanup
    el._abortController = controller
  },

  beforeUnmount(el: HTMLElement) {
    // Automatic cleanup of all listeners
    el._abortController?.abort()
  }
}

Directive Guide - Comprehensive directive development guide
Template System - Template syntax and directives
Custom Directives - Advanced directive patterns
Component System - Using directives with components

Directives

Built-in Directives

Conditional Directives

Loop Directives

Template Directives

Response Directives

Markdown Directives

Form Directives

Event Directives

Attribute Directives

Custom Directives

Simple Custom Directive

Advanced Custom Directive

Directive with Arguments

Parameterized Directive

Directive Composition

Multiple Directives

Directive Inheritance

Built-in Directive Modifiers

Event Modifiers

Model Modifiers

Async Directives

Async Directive Example

Directive Testing

Testing Custom Directives

Integration Testing

Performance Considerations

Efficient Directive Updates

Memory Management

Related Resources