Highlights

Draw attention to a single element with one popover and no sequence.

A Highlight is a Tour of one Step. There is no next button, no progress counter, and nothing to complete — the overlay dims the page, one element stays lit, and a single popover explains it. Reach for it when you have one thing to announce: a new control, a field that just changed meaning, a validation error worth pointing at.

Declaring one

The highlight controller action highlights the first Step of whatever Tour it finds, so all three authoring modes can drive it. ux_highlight() is the shorthand for the common case.

Component

<twig:Driver:Tour id="export-highlight">
    <button type="button" {{ ux_tour_action('highlight') }}>Where is export?</button>

    <twig:Driver:Step :order="1" title="Export" description="CSV and PDF are both available here">
        <button type="button" id="invoice-export">Export</button>
    </twig:Driver:Step>
</twig:Driver:Tour>

A one-Step Tour driven by highlight instead of start: no progress counter, no next button.

Twig builder

<button type="button"
        {{ ux_highlight('#invoice-export', 'Export', 'CSV and PDF are both available here') }}
        {{ ux_tour_action('highlight') }}>
    Where is export?
</button>

The first argument is the selector of the element to highlight — not the element carrying the attributes. ux_highlight() builds a one-Step Tour behind the scenes and hands it to the same pentiminax--ux-driver--tour controller a full Tour uses.

PHP builder

$highlight = $this->tourBuilder->create('export-highlight')
    ->addStep('#invoice-export', 'Export', 'CSV and PDF are both available here');

return $this->render('invoice/index.html.twig', ['highlight' => $highlight]);

<button type="button" {{ ux_tour(highlight) }} {{ ux_tour_action('highlight') }}>
    Where is export?
</button>

There is no ux_highlight() equivalent on the PHP side because none is needed: a Tour with one Step and the highlight action is exactly what the Twig function produces. Build it in PHP when the title or the selector depends on data.

`ux_highlight()` signature

ux_highlight(
    string $element,
    string|Markup $title,
    string|Markup|null $description = null,
    string $side = 'bottom',
    string $align = 'start',
    array $options = [],
)

side accepts top, right, bottom, or left; align accepts start, center, or end. The options array takes the same per-Step options a Tour Step accepts, so popover text and placement are tuned the same way:

{{ ux_highlight('#invoice-export', 'Export', 'CSV and PDF are both available', 'left', 'center', {
    doneBtnText: 'Got it',
    popoverClass: 'invoice-popover',
}) }}

See the Step reference for the full option list and the Security guide for what title and description escape.

Trusted markup

title and description accept Twig\Markup, so ux_driver_html() works here as it does everywhere:

{{ ux_highlight('#invoice-export', ux_driver_html('<strong>Export</strong>'), 'CSV and PDF') }}

Only pass markup you control. Security covers why.

Highlight or Tour

A Highlight is the right shape when the answer is one element. As soon as the explanation needs a second Step, write a Tour instead — the Tour gives you navigation buttons, the progress counter, and once. And if the help should stay on the page rather than be summoned, Hints are the persistent form.

Declaring one

ux_highlight() signature

Trusted markup

Highlight or Tour

`ux_highlight()` signature