Skip to main content

Placing the trigger

The built-in floating button is the default. ui.trigger controls it:

  • fab (default) — the package places the floating button itself.
  • inline — no modal; the form is part of the page (a contact form, say).
  • none — you place the trigger yourself.

A shop's order list in a browser, with a table of four orders and two buttons under it, and the package's floating "Send feedback" button in the bottom right corner of the page.

ui.position decides which corner the built-in button sits in: bottom-end (default), bottom-start, top-end or top-start. The corner is read in the writing direction, so end is the side a line of text ends on. A left-to-right page puts bottom-end at the bottom right, and a right-to-left page mirrors it to the bottom left, the way it mirrors the rest of its layout. Both view trees read it that way, so switching trees never moves the button.

The physical spellings bottom-right, bottom-left, top-right and top-left still work. Each means its left-to-right corner, so bottom-right is bottom-end: the same place on a left-to-right page, and mirrored on a right-to-left one. A value that is none of these eight puts the button in the default corner.

ui.fab_icon picks the glyph on the WireKit tree's floating button. It takes a WireKit icon alias and defaults to message, because a plus reads as "create something" rather than "give feedback". Set it to plus for the glyph earlier releases showed. A name WireKit does not declare keeps the plus instead of failing, and so does a WireKit older than 2.27. The glyph is drawn by your icon set, so without Blade Icons installed WireKit shows its plus whatever this says. The plain tree's button carries text and ignores the key.

A mode mount prop overrides this per widget, so one page can carry an inline contact form and a modal at the same time: <livewire:visual-feedback.report-widget mode="inline" />.

A contact page titled "Write to us" with the widget inline, as part of the page: the form "Send feedback" with name, email, category, subject, message and attachments, and a "Send" button at its end, without a screenshot button.

For your own trigger, use the component anywhere on the page:

<x-visual-feedback::trigger class="your-button-class">Report a problem</x-visual-feedback::trigger>

The trigger ships unstyled on purpose. In the plain view tree it renders a bare <button class="visual-feedback-trigger"> and the bundled stylesheet carries no rule for that class, so whatever you pass through class is the only styling it has — which is the point: a trigger sitting in your navigation should wear your buttons, not this package's. The class stays on the element as a stable hook, so you can target it as well.

Give it your own button styles, and if you have none to hand, give it at least 44×44 CSS px and a 16px font size: with browser defaults alone it renders around 21px tall, which is a hard target to hit on a phone. The WireKit tree needs none of this — its trigger is a WireKit button and inherits your design system's sizes.

If what you want is the floating button but somewhere else in the document — inside a layout that the widget's own position would fight, or on some pages only — the same component the package uses is public:

<x-visual-feedback::fab position="bottom-start" />

It takes position (the values above) and label. In the plain tree a slot replaces the label as the button's text. In the WireKit tree the button is a round 56 px icon button: a slot is icon markup, hidden from assistive technology, and the name stays label, so pass words as label there. Pair it with ui.trigger=none, or you get two floating buttons: the built-in one renders whenever the trigger is fab and the widget is in modal mode, and it does not know you placed another.

Both components render nothing at all while the package is switched off, so a trigger you placed yourself disappears with the rest of it rather than opening an empty dialog — see Abuse protection.

Or open the widget from your own code — any element, any framework. The widget listens for one window event:

<button type="button" id="report-a-problem">Report a problem</button>
// resources/js/app.js, or any script your page already loads
document.getElementById('report-a-problem')?.addEventListener('click', () => {
window.dispatchEvent(new Event('visual-feedback:open'));
});

The handler is bound in a script rather than written as an onclick attribute, and that is worth keeping. An inline event handler falls under script-src-attr, which falls back to script-src — so under any policy without 'unsafe-inline' the attribute is dropped and the button renders perfectly, looks right, and does nothing when clicked. The same failure as the one the Integration contract describes for style attributes, one level up and just as quiet. If your application has no content security policy the attribute form works fine; this one works either way.

The inline form takes the same component with a mode:

@livewire('visual-feedback.report-widget', ['mode' => 'inline'])

Per-instance mount props​

Eight props set one widget apart from the configuration, so a documentation page and a billing page in the same application can offer different forms. None of them can be changed or widened by the browser after mount, which is what makes them safe to trust on the server: categories, context, fields, withScreenshot and notice are sealed at mount and restored on every request, recipient has to stay an address the configuration permits, mode stays one the widget can render, and instance stays a name or none.

A request that breaks the seal gets no fallback to the configuration, which would offer every configured category and turn the capture back on. The widget switches the capture off instead and refuses to send until the page is reloaded, telling the reporter to copy their message first. Rotating APP_KEY breaks the seal of every page that is open at the time in the same way.

A request that tries to change a sealed prop leaves a warning in your log, naming the widget and the prop but never the value that arrived. It is written at most once a minute per prop, so a client that repeats the attempt cannot fill your log with it.

PropTypeDefaultWhat it does
mode?stringfrom ui.triggermodal or inline. inline renders the form in the page with no modal
categoriesarrayfrom categoriesthe category list this widget offers. Empty falls back to the configured list
contextarray[]context entries the host attaches to reports from this widget
fieldsarrayfrom fieldsthe mode of each field, off, optional or required, or the boolean this prop has always taken, e.g. ['subject' => false]. A key here wins over the configuration, in the form and in the validation; an absent key falls back to it. 'signed_in' => true shows signed-in reporters the name, email and phone fields as well, see A contact form beside the feedback widget
recipient?stringfrom mail.towhere this widget's reports are mailed
withScreenshot?boolnullnull follows the default (capture in modal mode only); false removes the capture from this widget, true adds it
notice?stringnulla sentence of yours above the fields, such as who reads a report and who gets a copy. It is rendered as text, and the dialog names it as its description, so a screen reader reads it when the panel opens
instance?stringnullthe name this widget answers to on a page with more than one modal widget, see Two modal widgets on one page
textsarray[]this widget's own words, see A contact form beside the feedback widget
messageMaxLength?intnullthe longest message, at most fields.message.max_length
rateLimit?intnullreports an hour one reporter may send through widgets of this instance name, on top of the global limits
urlQuery?boolnullwhether a report keeps the query of the page, for a page whose filters are its query; null follows metadata.url_query
<livewire:visual-feedback.report-widget
mode="inline"
:categories="['bug', 'billing']"
:fields="['subject' => false]"
:context="[['key' => 'plan', 'label' => 'Plan', 'value' => $team->plan]]"
recipient="billing@example.com"
:with-screenshot="false"
/>

The same names work through @livewire(), in their PHP spelling:

@livewire('visual-feedback.report-widget', [
'mode' => 'inline',
'categories' => ['bug', 'billing'],
'recipient' => 'billing@example.com',
'withScreenshot' => false,
])

Three details that are easy to get wrong:

  • The prop is categories, the property is availableCategories. Mount takes categories; the component holds the resolved list under the longer name.
  • A context entry is a plain array with key, label and value, optionally url and identifier. Entries whose values are not strings are dropped rather than rendered, so a typo here loses the entry silently. For context that should be on every report, use a context provider instead — see Configuration.
  • withScreenshot may narrow, never widen. With screenshot.strategy set to off the capture stays off everywhere, whatever a widget asks for.

recipient is visible in the page source​

Livewire serializes a component's public properties into a wire:snapshot attribute on the rendered element, and #[Locked] governs writes, not visibility. So a recipient you mount is readable by anyone who views the source of that page, and by any crawler that fetches it.

That is fine for an address you would print in a footer anyway. It is not fine for an internal team alias you would rather not publish. For that case, deliver through your own channel — see Delivery channels — and pick the address on the server, where the browser never sees it.

Two modal widgets on one page​

Every trigger opens the widget through the same window event, so a page that carries the page-wide widget in its layout and a second one with its own context, a project page for instance, would open both dialogs on one click. Give the second widget a name with instance, and aim its trigger at it:

<livewire:visual-feedback.report-widget instance="project" :context="$projectContext" />

<x-visual-feedback::trigger instance="project">Report a problem with this project</x-visual-feedback::trigger>

An open event that names an instance opens the widget of that name, and one that names none opens the widget without a name, so the layout's own button keeps opening the layout's widget alone. From your own code, the event carries the name in its detail:

window.dispatchEvent(new CustomEvent('visual-feedback:open', { detail: { instance: 'project' } }));

A name is letters, digits, - and _, up to 64 of them. Anything else is no name, and the widget then behaves as one without. <x-visual-feedback::fab> and <x-visual-feedback::standalone> take the same instance. In the WireKit views the modal is named after it, visual-feedback-project, because the kit opens a modal by name.

On a page without Livewire​

The widget above is a Livewire component, and a page served from a shared cache has no session, no cookie and no CSRF token for it. <x-visual-feedback::standalone /> is the same form for such a page. It renders from the configuration alone, so the markup is the same for every visitor and the page stays cacheable, and it sends the report itself, without Livewire.

Register its two routes where no session runs, for example in routes/api.php:

use Pushery\VisualFeedback\Standalone\StandaloneRoutes;

StandaloneRoutes::register(); // GET visual-feedback/standalone/form, POST visual-feedback/standalone/reports

Registering them is the opt-in. register('feedback') moves them under another prefix, and should they end up inside the web group, the session and CSRF middleware are taken off them again. Then place the component and keep <x-visual-feedback::scripts /> in the layout, as for the Livewire widget:

<x-visual-feedback::standalone />

What happens when a visitor opens it:

  • The form fetches a token. It holds the moment the form was opened, signed with the application key, and stands where the Livewire widget keeps that moment in the session. The time trap counts from it, and the widget waits out abuse.min_fill_seconds before it sends, so a quick reporter is never refused for it. A token stays valid for VISUAL_FEEDBACK_STANDALONE_TOKEN_TTL seconds, 7200 by default; a report sent later asks the reporter to send again, with a fresh token.
  • The report goes in one request, with its attachments and the screenshot. The capture and the editor are the same as in the Livewire widget, and so are the honeypot, the rate limits and a configured challenge.
  • Every reporter is a guest. The form shows the guest fields the configuration enables, and the privacy notice when one is configured.

The component renders nothing while the package is switched off or requires a sign-in, because neither can be decided for a page that is the same for everybody. It offers the configured form only: the per-instance props of the Livewire widget need a component that remembers them, and a cached page has none. The one exception is notice, which needs no remembering: the sentence is rendered into the page, the same for every visitor, above the fields and named by the dialog as its description.

<x-visual-feedback::standalone :notice="__('The shop answers you, and a copy goes to the operator of the platform.')" />

While the WireKit tree is served, the component draws the same form with WireKit's controls. A page without Livewire then takes Alpine from WireKit: set wirekit.scripts.bundle to csp, keep @wirekitScripts in the layout after <x-visual-feedback::scripts />, and load no Alpine of your own. That bundle carries Alpine's CSP build, so the page needs no unsafe-eval either.

Reports arrive through the same channels as every other report. To hand them to a system of your own, register a channel of your own, see Delivery channels.

On a page with a nonce-based content security policy, a cached copy carries the nonce of the request that filled the cache. Serve the bundles by source instead (script-src 'self'), as Serving the bundles yourself describes.

A contact form beside the feedback widget​

One component serves both, with different words and limits. The contact form is an inline widget with a name of its own:

<livewire:visual-feedback.report-widget
mode="inline"
instance="contact"
:categories="['question', 'sales']"
:texts="[
'heading' => __('Contact us'),
'submit' => __('Send message'),
'success' => __('Thank you, we will get back to you.'),
'error' => __('Your message could not be sent. Please try again.'),
'category' => __('Topic'),
'rate_limited' => __('Please wait :minutes minutes before sending another message.'),
'challenge_failed' => __('Please confirm again that you are a person.'),
]"
:message-max-length="5000"
:rate-limit="10"
/>

Every key of texts is optional, and a blank one takes the package's own line. A key the widget does not know, or a value that is no text, fails at the call site. :minutes in rate_limited is the time until the pot frees again, rounded up.

messageMaxLength can only lower fields.message.max_length, never raise it. rateLimit opens a pot of its own for every widget of that instance name, keyed like the built-in limits, by the signed-in user or the guest's address. It is counted on top of abuse.rate_limit, abuse.guest_rate_limit and abuse.global_rate_limit, never instead of them, so a widget can only be stricter than the floor. Every attempt counts, a refused one included, for the reason the built-in limits count them: otherwise failing attempts would cost the server and nothing else.

The widget seals all three with its other mount props, and its instance name with them, so a request can change none of them. The sender name and subject under mail.instances and the analytics names under matomo.instances follow the same sealed name.

Signed-in reporters write to it too. A feedback widget takes a signed-in reporter's name and address from the account and shows no identity fields. A contact form usually wants them shown, so somebody can answer from another address or leave a phone number. 'signed_in' => true in the fields prop shows a signed-in reporter the name, email and phone fields as well, filled from the account and held to their modes as a guest's are:

<livewire:visual-feedback.report-widget instance="contact" :fields="['phone' => 'optional', 'signed_in' => true]" />

The account stays the reporter, in the stored report and in the webhook payload. A name or an address changed in the form is where the reply goes: the mail's Reply-To follows it, while mail.reply_to_reporter is on, and the mail names it under "Reply to". A phone number given there is stored with the report.