The widget
<x-holler::widget /> draws everything a call needs on a plain Laravel page: the incoming-call toast with Accept and Decline, the call window (a tile per other person, your own picture in a corner, mute, camera, screen share, settings and hang up) and short notices such as "Call declined". Put it once in your layout, after Holler::routes() is registered.
The widget is the CallWidget from @packstub/holler, running over its CallClient engine. Both are plain ES modules without a framework, served by the package from holler/assets/, so there is nothing to publish or bundle.
Attributes
| Attribute | Default | Does |
|---|---|---|
routes |
holler. |
the route name prefix given to Holler::routes() |
pop-out |
HOLLER_POP_OUT (true) |
open each call in a window of its own, with a chip on the page |
styles |
true |
load the package stylesheet; false to bring your own |
nonce |
Vite::cspNonce() |
the Content-Security-Policy nonce put on the widget's script and stylesheet tags; set automatically when your app calls Vite::useCspNonce() |
options |
[] |
more CallWidget options, merged key by key over the ones the component builds: labels, video, windowFeatures, callSelector and the rest |
name |
holler |
the global the widget is kept in, window.holler, for your own scripts |
<x-holler::widget routes="team.calls." :pop-out="false" :options="['windowFeatures' => 'popup=yes,width=640,height=480']" />
Call buttons
Any element with data-holler-call="<user id>" is a call button: a click rings that person. Clicked during a call, the widget asks what to do with the call you are on: add the person to it, put it on hold and ring them, or end it and ring them. <x-holler::button> is a shortcut for it:
<x-holler::button :user="$user" />
<x-holler::button :user="$user->id" class="btn btn-sm">Call {{ $user->first_name }}</x-holler::button>
It takes a user or an id, merges your attributes and slot (the label is "Call" without one), and renders nothing for the signed-in person. Given a user, it also puts their name in data-holler-name, which the widget shows with its question (name="..." sets it for an id). To add the person at once as before, pass :options="['duringCall' => 'add']" to the widget. It does not ask whether the call is allowed; the server does when it is clicked.
Scripting
The widget is kept in window.holler (or the name you gave it). callUser(id), accept(), decline(), hangUp(), toggleMute(), toggleCamera() and toggleShare() do the same as its buttons:
window.holler.callUser(5)
holler:ready fires on window with { widget } once the widget is built. After that, every event of the engine bubbles from the widget as holler:<type> (statechange, incoming, peers, peerstate, quality, devices, ended and others), plus holler:sharing with { peer, sharing, spotlight } when someone's screen takes the stage:
document.addEventListener('holler:ended', (event) => console.log('call ended', event.detail))
Microphone, camera and speaker
The cog in the call window opens three menus: the microphone, the camera and, where the browser can choose one (Chrome, Edge and recent Firefox), the speaker. A choice applies at once, for everyone on the call and without the call reconnecting, and is remembered in that browser for the next call; nothing about it is sent to the server. A remembered device that is unplugged later falls back to the system's own. Browsers name the devices only after the person allowed the camera or the microphone, which on a call they have.
:options="['devices' => false]" leaves the settings out, and 'storageKey' => null stops remembering the choice.
A call in the background
The ring is easy to miss in a tab the person is not looking at, so the widget does two more things while a call rings there:
- The tab's title alternates with "Ana is calling you" until the call is answered, declined or given up, or the person is back on the tab.
- A system notification, once the person allowed notifications for your site. Browsers only show that question after a click, so the widget never asks by itself: the call's settings carry a link, "Notify me about calls when this tab is in the background", and a button of your own can ask at a better moment:
<button type="button" onclick="window.holler.enableNotifications()">Notify me about calls</button>
window.holler.canNotify says whether there is still something to ask. One notification per call, however many tabs are open, and a click on it brings the tab back. :options="['notifications' => false]" turns both off. A notification needs a tab of your app to be open somewhere: the package runs no push service.
The pop-out window
A browser closes a WebRTC connection on every full page load, so by default each call opens in a small browser window of its own. The page shows a chip with the people on the call and the timer, a button to bring the window back and one to hang up, and is free to navigate, reload or close.
- Reloading the pop-out reconnects the call. Closing it hands the call back to the page, which continues it there.
- If the browser blocks the pop-out, the call opens in the page instead, with a short notice.
- The pop-out's address names the call (
/calls/window?call=12) or the person to ring (?callee=5), but an address alone never rings anyone or answers a call. The page that opens the window leaves a one-time token inlocalStorage(valid for 60 seconds, read once), and the pop-out acts only when it finds it. Opened from a link, the page only shows the call. - The pop-out page is never shown inside another site's frame.
HOLLER_POP_OUT=false (or :pop-out="false") keeps the call in the page, which suits a single-page app. A full page load then reconnects the call: the other side sees "Reconnecting…" for a few seconds, then the video is back. When one side stays away longer than HOLLER_RECONNECT_TIMEOUT (15 seconds), it is dropped from the call.
Restyling
Every class is holler-*, and the colours and sizes are custom properties on .holler:
.holler {
--holler-accent: #d97706;
--holler-bg: #1c1917;
--holler-radius: 0.75rem;
--holler-width: 28rem;
}
The others are --holler-fg, --holler-dim, --holler-stage, --holler-tile, --holler-control, --holler-danger, --holler-success (each with a -hover where it has one), --holler-z and --holler-font. When a few variables are not enough, set :styles="false" and write your own stylesheet against the class names.
Texts and translations
The widget's labels ship in English, German, Romanian and Russian, and follow the app's locale. Publish them to change a text or add a language:
php artisan vendor:publish --tag=holler-translations
They land in lang/vendor/holler/en/ui.php (the widget) and messages.php (the server's messages, such as "This person is on another call."); copy them to lang/vendor/holler/<locale>/ for another language, and the app's locale picks them up. The widget gets its labels from these files. options can change a few for one page (:options="['labels' => ['accept' => 'Pick up']]"); the rest keep their translations.
Your own markup
The widget renders eight views from template functions: incoming (the toast), chip, window, tile (one per person who answered; someone added to a running call shows as a Ringing line over the stage until then), person (one per person the search found), held (the bar of a call on hold), prompt (the question when Call is pressed during a call) and notice. Each is rendered once when it appears and kept current through a few data-holler-* hooks: text, show, class, attr, src, video and action. Pass in your own markup and keep whichever hooks you need. Templates are functions, so they cannot come through a Blade attribute; set them from a script:
<x-holler::widget :options="['startPolling' => false]" />
<script type="module">
window.addEventListener('holler:ready', ({ detail: { widget } }) => {
widget.templates.incoming = (v) => `
<div class="my-toast" data-holler-scope>
<b data-holler-text="peerName"></b> ${v.labels.incoming}
<button data-holler-action="accept">${v.labels.accept}</button>
<button data-holler-action="decline">${v.labels.decline}</button>
</div>`
widget.start()
})
</script>
startPolling: false keeps the widget idle until widget.start(), so the template is in place before the first call can ring. The view model each template and hook reads is documented in the @packstub/holler README, together with subclassing CallWidget for deeper changes.
Without the widget
For a UI of your own or a component in your frontend framework, use the engine on its own:
import { CallClient, HttpSignaling } from '{{ Holler::asset('index.js') }}'
Or npm install @packstub/holler. Give it the routes, the CSRF token, Holler::rtcConfiguration(), Holler::context()->hasVideo() and Holler::maxParticipants(). Its README documents the events (incoming, localstream, remotestream, peers, statechange, ended) and the controls (callUser, invite, search, hold, resumeHeld, accept, decline, hangUp, setMuted, setCameraOff, shareScreen, devices, setDevice). The routes and their JSON are in Endpoints.