JS Helpers

Lightweight helpers that let you react to component events, update the DOM, and trigger toasts — all inline in your Blade templates.

Overview

Boson ships a tiny JavaScript layer that works alongside its Blade components. There's no framework to learn, no build config to change, and no JS files to write — everything happens through HTML attributes right in your templates.

The core idea is simple: Boson components emit events (like a form succeeding or a modal opening), and you respond to them with small inline expressions using on: attributes.

Inside those handlers, Boson gives you a handful of helpers — $toast, $(), $match, and $data — that cover the most common needs without reaching for a full JS framework.

The Event System

Add an on:event attribute to any element to run JavaScript when that event fires. Boson handles both its own custom events and standard DOM events.

Boson component events

{{-- React to a form submission completing successfully --}}
<x-boson::form fetch action="/team" method="PUT" on:success="$toast.success('Team updated!')">
    ...
</x-boson::form>

{{-- React to a modal opening --}}
<x-boson::modal name="confirm" on:open="console.log('Modal opened')">
    ...
</x-boson::modal>

Native DOM events

{{-- Standard click handler --}}
<x-boson::button on:click="$toast.success('Clicked!')">
    Click me
</x-boson::button>

{{-- Keyboard events --}}
<x-boson::input name="search" on:keydown="console.log('typing...')" />

Boson supports these custom events: submitting, submitted, success, error, open, close, change, select, and deselect.

Native events like click, input, keydown, focus, blur, and more are also supported.

Available Helpers

Inside any on: handler, these variables are automatically available:

$toast — Toast notifications

Trigger toast notifications from any event handler. Supports success, warning, and danger variants.

$toast.success('Changes saved!')
$toast.warning('Are you sure?')
$toast.danger('Something went wrong.')


$toast.danger({ heading: 'Upload failed', text: 'The file exceeds the 5MB limit.' })

{{-- Using $toast in a handler --}}
<x-boson::form fetch action="/settings" method="PUT" on:success="$toast.success('Settings saved!')" on:error="$toast.danger('Save failed.')">
    ...
</x-boson::form>

$() — DOM helper

A chainable jQuery-like helper for updating the DOM. Pass any CSS selector and chain methods to manipulate matched elements.

$('#user-name').text('Jane Doe')


$('#status-badge').data('color', 'green')


$('#avatar').attr('src', '/new-photo.jpg')


$('#loading').toggle(false)
$('#content').toggle(true)


$('#badge').text('Active').data('color', 'green')

Available methods:

• .text(value) — set text content
• .class(value) — replace class list
• .data(key, value) — set a data attribute
• .attr(key, value) — set any attribute
• .toggle(show) — show/hide element

$data — Response data

A shorthand for $event.detail.data. When a Boson component dispatches an event with a data payload (like a form response from your controller), $data gives you direct access.

{{-- Access response data after a form submission --}}
<x-boson::form fetch action="/team" method="PUT"
    on:success="$('#team-name').text($data.name)">
    ...
</x-boson::form>

{{-- Your controller returns JSON like: { "data": { "name": "New Team Name" } } --}}

$match — Value lookup

Works like PHP's match expression — maps a value to a result using a lookup object. Useful for converting statuses, roles, or any value into display text or styling.

$match($data.status, { pending: 'amber', active: 'green', archived: 'gray' })


$match($data.role, { admin: 'Administrator', user: 'User' }, 'Unknown')


$match(value, { a: '1', b: '2' }, 'default')

$event & this

$event is the raw DOM event (or CustomEvent) object. this refers to the element with the on: attribute.

{{-- Access the full event object --}}
<div on:click="console.log($event.target)">...</div>

{{-- Reference the handler element --}}
<x-boson::button on:click="this.textContent = 'Clicked!'">
    Click me
</x-boson::button>

Putting It All Together

Here's a realistic example: a form that updates a status badge, shows a toast, and toggles a section — all without writing a single JavaScript file.

{{-- Status badge somewhere on page --}}
<x-boson::badge id="project-badge" color="gray">Draft</x-boson::badge>

{{-- Update form --}}
<x-boson::form fetch action="/project" method="PUT"
    on:success="
        $('#project-badge').text($data.status).data('color', $match($data.status, { draft: 'gray', published: 'green', archived: 'amber' }));
        $toast.success('Project updated!');
        $('#published-section').toggle($data.status === 'published')
    "
    on:error="$toast.danger('Something went wrong.')"
>
    <x-boson::field>
        <x-boson::label for="status">Status</x-boson::label>
        <x-boson::select name="status" id="status">
            <x-boson::select.option value="draft">Draft</x-boson::select.option>
            <x-boson::select.option value="published">Published</x-boson::select.option>
            <x-boson::select.option value="archived">Archived</x-boson::select.option>
        </x-boson::select>
    </x-boson::field>

    <x-boson::button type="submit">Save</x-boson::button>
</x-boson::form>

{{-- Conditionally visible section --}}
<div id="published-section" hidden>
    <p>This project is now live.</p>
</div>

Quick Reference