Scoreboards

Ui::scoreboard() lays out key figures in a row, which scrolls sideways by dragging when it runs out of room, as a toolbar does. Open it with ->slot() and close it with Ui::end(), and write each figure with Ui::scoreboardItem() in between.

Figures

Each item shows a label as its title, the value as the figure, and a comment under it, all escaped, with a thin line between items. A unit, such as 'ms', shows smaller after the figure. success: true and danger: true color the figure. A null value shows "No data" in place of the figure, so a figure without data does not leave a blank.

<?php Ui::scoreboard()->slot() ?>
    {{ Ui::scoreboardItem(label: 'Orders', value: '1,284', comment: 'this month') }}
    {{ Ui::scoreboardItem(label: 'Average session', value: '4.2', unit: 'min', comment: 'this month') }}
    {{ Ui::scoreboardItem(label: 'Uptime', value: '99.98%', comment: 'last 30 days', success: true) }}
    {{ Ui::scoreboardItem(label: 'Failed jobs', value: 3, comment: 'since yesterday', danger: true) }}
    {{ Ui::scoreboardItem(label: 'Churn', value: null, comment: 'not enough data yet') }}
<?php Ui::end() ?>

Trends

change shows how the figure moved, such as '14.9%', in a pill beside it. positive: true tints the pill green with an up arrow and negative: true red with a down arrow, and without either the pill is grey. A trend without a change shows the arrow alone. The figure keeps its own color, and screen readers hear "Increased" or "Decreased" before the change.

compare takes the current and previous values, and works out the change as a percentage and its direction, when change, positive and negative are not set. A previous value of zero gives the direction alone. For a figure where lower is better, such as a response time, inverse: true tints a fall green and a rise red, while the arrow still points the way the figure moved.

sparkline takes recent values, oldest first, and draws them as a small line under the figure, scaled between the lowest and highest value, with a dot on the latest. It is drawn on the server, with no script, in the trend's green or red, and the primary color otherwise.

<?php Ui::scoreboard()->slot() ?>
    {{ Ui::scoreboardItem(
        label: 'Revenue',
        value: '$48,210',
        change: '14.9%',
        positive: true,
        sparkline: [36200, 38900, 37400, 41950, 43100, 45800, 48210],
        comment: 'previous month: $41,950'
    ) }}

    {{ Ui::scoreboardItem(
        label: 'Signups',
        value: 31,
        compare: [31, 42],
        sparkline: [48, 51, 44, 42, 39, 35, 31],
        comment: 'previous month: 42'
    ) }}

    {{ Ui::scoreboardItem(
        label: 'Visits',
        value: '12,408',
        change: '0.4%',
        sparkline: [12100, 12650, 12210, 12380, 12590, 12360, 12408],
        comment: 'about the same as last week'
    ) }}

    {{ Ui::scoreboardItem(
        label: 'Response time',
        value: 312,
        unit: 'ms',
        compare: [312, 340],
        inverse: true,
        sparkline: [355, 348, 362, 340, 331, 318, 312],
        comment: 'lower is better'
    ) }}
<?php Ui::end() ?>

Markers

An item can have a marker, as an option can. icon takes icon classes and shows them in a tile beside the text, tinted with the color when there is one. Without an icon, color shows a swatch before the figure, and image a small image. A color that is not a hex, rgb(), hsl() or var() color is left out.

<?php Ui::scoreboard()->slot() ?>
    {{ Ui::scoreboardItem(label: 'Customers', value: '2,318', icon: 'ph ph-users', comment: '84 new this week') }}
    {{ Ui::scoreboardItem(label: 'Top seller', value: 'Desk lamp', icon: 'ph ph-star', color: 'var(--bs-warning-base)', comment: '312 sold') }}
    {{ Ui::scoreboardItem(label: 'Status', value: 'Shipped', color: 'var(--bs-success-base)', comment: 'since 3 Nov') }}
    {{ Ui::scoreboardItem(label: 'Supplier', value: 'Acme Supply', image: asset('images/acme-supply.svg'), comment: 'restocks weekly') }}
<?php Ui::end() ?>

Goal meters

meter adds a bar under the figure that fills to a percentage, and with no value the figure shows that percentage. The bar fills in green, or in red with inverse: true, for a rate where higher is worse. Screen readers read it as a progress bar.

<?php Ui::scoreboard()->slot() ?>
    {{ Ui::scoreboardItem(label: 'Open rate', meter: 64, comment: '120 unread') }}
    {{ Ui::scoreboardItem(label: 'Goal', value: '37 of 50', meter: 74, comment: '13 posts to go') }}
    {{ Ui::scoreboardItem(label: 'Unsubscribe rate', meter: 3, inverse: true, comment: '12 opted out') }}
<?php Ui::end() ?>

Links and help

href makes the whole item a link, such as to the list or report behind the figure, which goes through url() like other widget paths. Links inside a slot still work on their own. tooltip adds an icon beside the title that shows the text on hover.

<?php Ui::scoreboard()->slot() ?>
    {{ Ui::scoreboardItem(
        label: 'Open orders',
        value: 18,
        comment: 'view the list',
        href: route('reference.ui.scoreboards').'#scoreboard-links'
    ) }}

    {{ Ui::scoreboardItem(
        label: 'Conversion rate',
        value: '3.4%',
        comment: 'last 30 days',
        tooltip: 'Orders placed divided by visits, over the last 30 days.'
    ) }}

    {{ Ui::scoreboardItem(
        label: 'Average order',
        value: '$86.40',
        comment: 'view the report',
        href: route('reference.ui.charts'),
        tooltip: 'Revenue divided by orders, before refunds.'
    ) }}
<?php Ui::end() ?>

Markup in a figure

For a figure or comment with markup, such as a link, open the item with ->slot(): what prints after it is the figure, and Ui::slot('comment') switches to the comment, up to Ui::end(). Open it with ->slot('comment') when only the comment has markup. Markup in a slot is printed as it is, so escape any values in it.

<?php Ui::scoreboard()->slot() ?>
    <?php Ui::scoreboardItem(label: 'Customer')->slot() ?>
        <a href="{{ route('reference.ui.scoreboards') }}#scoreboard-slots">
            Jane Doe
        </a>
    <?php Ui::slot('comment') ?>
        Email:
        <a href="mailto:jane@example.com">
            jane@example.com
        </a>
    <?php Ui::end() ?>

    <?php Ui::scoreboardItem(label: 'Total', value: '$1,240.00')->slot('comment') ?>
        Tax: $112.73 &bull; Shipping: $15.00
    <?php Ui::end() ?>
<?php Ui::end() ?>

Thumbnails

Ui::scoreboardThumbnail() is an item that shows an image, such as a product photo, with the label as its text alternative.

<?php Ui::scoreboard()->slot() ?>
    {{ Ui::scoreboardThumbnail(image: asset('images/desk-lamp.svg'), label: 'Desk lamp') }}
    {{ Ui::scoreboardItem(label: 'Product', value: 'Desk lamp', comment: 'SKU: LAMP-01') }}
    {{ Ui::scoreboardItem(label: 'In stock', value: 48, comment: 'reorder at 10') }}
<?php Ui::end() ?>

Charts

A pie or bar chart written directly inside a scoreboard lays out as one of its items, at the height of the row.

<?php Ui::scoreboard()->slot() ?>
    {{ Ui::pieChart(values: [
        'Published' => [84, 'var(--bs-success-base)'],
        'Drafts' => [12, 'var(--bs-warning-base)'],
        'Deleted' => [18, 'var(--bs-danger-base)'],
    ]) }}

    {{ Ui::barChart(values: [
        'Published' => [84, 'var(--bs-success-base)'],
        'Drafts' => [12, 'var(--bs-warning-base)'],
        'Deleted' => [18, 'var(--bs-danger-base)'],
    ]) }}

    {{ Ui::scoreboardItem(label: 'Posts', value: 114, comment: 'all time') }}
<?php Ui::end() ?>

Markup

The components write the scoreboard element, which you can also write by hand. Each scoreboard-item title-value holds an h4 title, the figure, and a description line, and the items sit in a data-control="toolbar" element. A positive or negative class on the figure adds a green or red arrow after it.

<div class="scoreboard">
    <div data-control="toolbar">
        <div class="scoreboard-item title-value">
            <h4>
                Orders
            </h4>
            <p>
                1,284
            </p>
            <p class="description">
                this month
            </p>
        </div>

        <div class="scoreboard-item title-value">
            <h4>
                Revenue
            </h4>
            <p class="positive">
                $48,210
            </p>
            <p class="description">
                previous month: $41,950
            </p>
        </div>

        <div class="scoreboard-item title-value">
            <h4>
                Signups
            </h4>
            <p class="negative">
                31
            </p>
            <p class="description">
                previous month: 42
            </p>
        </div>

        <div class="scoreboard-item title-value">
            <h4>
                Top seller
            </h4>
            <p>
                <i class="ph ph-star"></i>
                Desk lamp
            </p>
            <p class="description">
                312 sold
            </p>
        </div>
    </div>
</div>

Methods

Method	Description
Ui::scoreboard()	opens a scoreboard with ->slot(), closed by Ui::end().
Ui::scoreboardItem(...)	a figure, with the arguments below. Its ->slot() captures the figure, and Ui::slot('comment') the comment.
Ui::scoreboardThumbnail($image, $label)	an item that shows an image.

Ui::scoreboardItem() takes these arguments:

Argument	Description
label	the title above the figure.
value	the figure, or null for no data.
unit	a unit shown smaller after the figure.
comment	the line under the figure.
icon	icon classes, shown in a tile beside the text.
color	a color, which tints the icon tile, or shows as a swatch without an icon.
image	the address of a small image before the figure.
change	how the figure moved, shown in a pill beside it.
compare	the current and previous values, which give the change and its direction.
positive, negative	an up or down trend, which tints the pill and adds an arrow.
sparkline	recent values, drawn as a small line under the figure.
success, danger	colors the figure green or red.
meter	a percentage that adds a goal meter.
inverse	for a figure where lower is better: a fall is green, a rise red, and the goal meter fills in red.
href	makes the whole item a link.
tooltip	text shown from an icon beside the title.

Any other named argument, such as id or class, is added to the item's element, and likewise for the scoreboard itself.