Buttons

The Ui facade renders buttons from your views: plain buttons and links, buttons that run an AJAX handler, icon-only buttons and buttons with a keyboard shortcut. Each call takes PHP named arguments, and any argument the button does not know becomes an HTML attribute.

Every Ui call returns an object that implements Laravel's Htmlable contract, so Blade's escaped {{ }} output prints it as HTML and you do not need {!! !!}. The call is the same in every view, with no component tags to learn: the arguments are the named arguments of a static method, so your editor can suggest them as you type.

Variants

A styling flag picks the look: primary, secondary or danger render Bootstrap's solid button (btn-solid) in that theme. Without a flag, the button renders Bootstrap's plain btn class. When you pass more than one flag, the first in that order wins.

{{ Ui::button(label: 'Primary', primary: true) }}
{{ Ui::button(label: 'Secondary', secondary: true) }}
{{ Ui::button(label: 'Danger', danger: true) }}
{{ Ui::button(label: 'Default') }}

Outline, subtle and link

The class argument merges extra classes into the button's own, so any Bootstrap variant and theme works. Leave the styling flag out and pass the variant and theme classes yourself, such as btn-outline theme-primary, btn-subtle theme-primary or btn-link.

{{ Ui::button(label: 'Outline', class: 'btn-outline theme-primary') }}
{{ Ui::button(label: 'Outline danger', class: 'btn-outline theme-danger') }}
{{ Ui::button(label: 'Subtle', class: 'btn-subtle theme-primary') }}
{{ Ui::button(label: 'Link', class: 'btn-link') }}

Sizes

Sizes go through class too: btn-xs, btn-sm and btn-lg, next to the default. The same classes on a btn-group, as btn-group-sm or btn-group-lg, size every button inside it.

{{ Ui::button(label: 'Extra small', primary: true, class: 'btn-xs') }}
{{ Ui::button(label: 'Small', primary: true, class: 'btn-sm') }}
{{ Ui::button(label: 'Default', primary: true) }}
{{ Ui::button(label: 'Large', primary: true, class: 'btn-lg') }}

With an icon

The icon argument renders an icon before the label. It takes icon classes, such as ph ph-floppy-disk or ph ph-trash.

{{ Ui::button(label: 'Save', icon: 'ph ph-floppy-disk', primary: true) }}
{{ Ui::button(label: 'Download', icon: 'ph ph-download-simple', secondary: true) }}
{{ Ui::button(label: 'Delete', icon: 'ph ph-trash', danger: true) }}

Links

An href renders an <a> element styled as a button, in place of a <button>. Pass target and rel as you would on any link, since they are attributes.

{{ Ui::button(label: 'Back to the reference', href: route('reference.index'), icon: 'ph ph-arrow-left', secondary: true) }}
{{ Ui::button(
    label: 'Larajax docs',
    href: 'https://larajax.org',
    icon: 'ph ph-arrow-square-out',
    class: 'btn-link',
    target: '_blank',
    rel: 'noopener'
) }}

Attributes

Any argument the button does not know becomes an attribute on the element, with its camel case name written in kebab case: dataRequestFlash renders data-request-flash and ariaLabel renders aria-label. The values follow these rules:

• A data attribute set to true renders as "true", which the framework reads as on.
• An attribute set to false is left out.
• Any other attribute set to true, such as disabled, repeats its name: disabled="disabled".
• class merges with the button's own classes, while any other attribute replaces the button's value. Buttons render type="button", so pass type: 'submit' for a submit button.

{{ Ui::ajaxButton(label: 'Flash a message', handler: 'onFlashMessage', secondary: true, dataRequestFlash: true) }}
{{ Ui::button(label: 'Hover for a title', title: 'Any argument the button does not know becomes an attribute') }}
{{ Ui::button(label: 'Disabled', secondary: true, disabled: true) }}

Groups and text

A btn-group element joins the buttons inside it into one bar. A button-text span sets muted text beside a button, such as an "or Cancel" link next to a save button, and styles a link inside it to match.

<div class="btn-group">
    {{ Ui::button(label: 'Day', secondary: true) }}
    {{ Ui::button(label: 'Week', secondary: true) }}
    {{ Ui::button(label: 'Month', secondary: true) }}
</div>

<div>
    {{ Ui::ajaxButton(label: 'Save draft', handler: 'onSaveDraft', primary: true, dataRequestFlash: true) }}
    <span class="button-text">
        or
        <a href="{{ route('reference.index') }}">
            Cancel
        </a>
    </span>
</div>

AJAX button

Ui::ajaxButton() runs a handler on the controller when clicked, through Larajax's data-request attribute. requestData sends extra values with the request, as an array that the button encodes as JSON, and the handler reads them with input(). Since other arguments are attributes, the Larajax request attributes work as they are: dataRequestConfirm asks first and runs the request only when the visitor accepts, and dataRequestFlash shows the flash messages the handler returns.

{{ Ui::ajaxButton(label: 'Flash a message', handler: 'onFlashMessage', primary: true, dataRequestFlash: true) }}
{{ Ui::ajaxButton(
    label: 'Archive item 7',
    handler: 'onArchiveItem',
    secondary: true,
    requestData: ['item' => 7],
    dataRequestFlash: true
) }}
{{ Ui::ajaxButton(
    label: 'Run after confirming',
    handler: 'onConfirmedAction',
    danger: true,
    dataRequestConfirm: 'Run this action?',
    dataRequestFlash: true
) }}

The handlers live in a trait on the page's controller:

<?php

namespace App\Controllers\Reference\UiController;

use Larajax\Classes\AjaxResponse;

/**
 * ButtonHandlers holds the AJAX handlers behind the Buttons page.
 */
trait ButtonHandlers
{
    /**
     * onFlashMessage shows a flash message, as the handler for the plain AJAX button.
     */
    public function onFlashMessage(): AjaxResponse
    {
        return ajax()->flash('success', 'Hello from the server.');
    }

    /**
     * onConfirmedAction runs after the visitor accepts the confirmation prompt.
     */
    public function onConfirmedAction(): AjaxResponse
    {
        return ajax()->flash('success', 'The action ran after you confirmed it.');
    }

    /**
     * onArchiveItem reads the item number sent as request data.
     */
    public function onArchiveItem(): AjaxResponse
    {
        $itemNumber = (int) input('item');

        return ajax()->flash('success', "Item {$itemNumber} archived.");
    }

    /**
     * onRefreshData stands in for a refresh, as the handler for the icon button and the hotkeys.
     */
    public function onRefreshData(): AjaxResponse
    {
        return ajax()->flash('info', 'The data was refreshed.');
    }

    /**
     * onSaveDraft stands in for a save, as the handler for the hotkey and grouped buttons.
     */
    public function onSaveDraft(): AjaxResponse
    {
        return ajax()->flash('success', 'Draft saved.');
    }
}

Larajax's AJAX handlers and responses guides cover how handlers are found and what they can return.

Loading state

dataAttachLoading disables the button and shows a spinner on it while its request runs, so the visitor cannot send it twice. The handler here sleeps for a moment so you can see it.

{{ Ui::ajaxButton(
    label: 'Run a slow request',
    handler: 'onSlowRequest',
    primary: true,
    dataAttachLoading: true,
    dataRequestFlash: true
) }}

Icon button

Ui::iconButton() renders the icon alone, as a btn-icon-link button with the icon classes on the button itself. The label becomes its title, which the browser shows on hover and screen readers announce. danger turns the icon red on hover, for destructive actions. With a handler it runs that handler, and it takes the same request attributes as an AJAX button.

{{ Ui::iconButton(label: 'Refresh', icon: 'ph ph-arrows-clockwise', handler: 'onRefreshData', dataRequestFlash: true) }}
{{ Ui::iconButton(
    label: 'Delete',
    icon: 'ph ph-trash',
    handler: 'onConfirmedAction',
    danger: true,
    dataRequestConfirm: 'Delete this item?',
    dataRequestFlash: true
) }}

btn-icon-link is the library's own class. Bootstrap 6's btn-icon is a different, square button.

Hotkeys

A hotkey clicks the button from the keyboard. It takes one shortcut as a string, such as 'alt+shift+d', or several as an array, such as ['ctrl+s', 'cmd+s'] so the same shortcut works on Windows and macOS. Hovering the button then shows a tooltip with the label and the shortcut, written with key symbols: ctrl shows as ⌃, cmd as ⌘, shift as ⇧, alt as ⌥ and enter as ↵, and other keys in capitals. Try Ctrl + S on the demo page.

{{ Ui::ajaxButton(
    label: 'Save draft',
    handler: 'onSaveDraft',
    primary: true,
    hotkey: ['ctrl+s', 'cmd+s'],
    dataRequestFlash: true
) }}
{{ Ui::popupButton(label: 'Open a dialog', handler: 'onLoadDialog', secondary: true, hotkey: 'alt+shift+d') }}
{{ Ui::iconButton(
    label: 'Refresh',
    icon: 'ph ph-arrows-clockwise',
    handler: 'onRefreshData',
    hotkey: 'alt+shift+r',
    dataRequestFlash: true
) }}

Every button kind takes hotkey. It renders the data-hotkey attribute of the input hotkey control, which lists the keys you can use, and the data-tooltip-* attributes of the tooltip.

Fluent props

Methods chained on the result set the same props as the named arguments: primary(), icon(), handler(), requestData() and so on. A method called with no argument sets its prop to true. Chained methods only set props, so attributes such as dataRequestFlash still go in the named arguments. Since label is the first argument, Ui::button('Publish') works without its name.

{{ Ui::button(label: 'Publish')->primary()->icon('ph ph-paper-plane-tilt') }}
{{ Ui::ajaxButton(label: 'Archive item 7', dataRequestFlash: true)
    ->handler('onArchiveItem')
    ->requestData(['item' => 7])
    ->secondary() }}

Arguments

Ui::button()

Argument	Description
label	the button text, escaped.
href	renders an <a> link with this address in place of a <button>.
icon	icon classes, rendered before the label.
primary	primary styling, btn-solid theme-primary. Default: false.
secondary	secondary styling, btn-solid theme-secondary. Default: false.
danger	danger styling, btn-solid theme-danger. Default: false.
hotkey	a keyboard shortcut, or an array of them, that clicks the button and shows in a tooltip.

Any other argument becomes an attribute, as described in Attributes.

Ui::ajaxButton()

Takes the arguments of Ui::button() except href, plus:

Argument	Description
handler	the AJAX handler to run, such as onSave, rendered as data-request.
requestData	an array of extra values to send with the request, rendered as data-request-data.

Ui::iconButton()

Argument	Description
label	the button's title, shown on hover and read by screen readers.
icon	icon classes, set on the button itself.
handler	an AJAX handler to run when clicked.
danger	turns the icon red on hover. Default: false.
hotkey	a keyboard shortcut, or an array of them, that clicks the button.

Ui::popupButton() opens a handler's response in a dialog, and its arguments are listed on the Popups page.