Skip to main content

Embed Brella widgets on a single-page website

C
Written by Customer Success

The legacy schedule, speakers and sponsors widgets render once, when the widget script loads, into the element with the ID brella-widget. On a single-page website (React, Vue, Next.js, Angular or a similar framework) that element often appears only after a client-side page change, so the widget stays empty. Turn on the widget's SPA mode to render it after each page change.

These instructions apply to the legacy loader from widget.brella.io. For an embed created in Widgets, use Install website widgets V2, which has its own rendering instructions.

Before you start

  • You need the complete legacy code installed on your website. Keep its script address and make a copy before changing it.

  • You need to edit the HTML or the templates of your website. If someone else manages the site, give them the widget code and this article. The Turn on SPA mode section is for your website developer.

Create a new embed

Open Widgets and choose Schedule, Speakers or Sponsors. The page creates V2 embeds. See Switch to website widgets V2 before replacing existing legacy code.

How the widget code works

Legacy embed code has three parts:

<!-- Inject Brella Widget Here -->
<div id="brella-widget">
<script type="text/props">
{
"joinCode": "youreventjoincode",
"widgetType": "schedule-tracks"
}
</script>
</div>
<script async src="..."></script>
<!-- Inject Brella Widget Here End -->
  • The div with the ID brella-widget is where the widget renders. The script type="text/props" inside it holds the settings as JSON. joinCode is your event's join code; widgetType is schedule-tracks, speakers or sponsors.

  • The last script line loads the widget from Brella. The widget is one file: its styles are injected by the script, and it loads event data from Brella's API.

Without SPA mode, the script renders the widget once when it loads. If brella-widget is not in the page at that moment, nothing renders.

Turn on SPA mode

  1. Paste the div part where the widget goes, in the page or component your framework renders.

  2. Add this line before the widget script line, so it runs first:

    <script>window.brellaWidgetOptions = { spaMode: true, renderDelay: 0 }</script>

  3. Keep the script line from your installed legacy code after it.

Use this order for the elements on your page. Replace YOUR_EVENT_JOIN_CODE with the value from your copied code. Replace the script address with the exact address from that code, and keep your other legacy widget settings.

<div id="brella-widget">
<script type="text/props">
{
"joinCode": "YOUR_EVENT_JOIN_CODE",
"widgetType": "schedule-tracks"
}
</script>
</div>
<script>window.brellaWidgetOptions = { spaMode: true, renderDelay: 0 }</script>
<script async src="COPY_THE_SCRIPT_ADDRESS_FROM_YOUR_LEGACY_CODE"></script>

Do not paste the placeholder script address into your live website. Ask your developer to test both a direct page load and navigation to the page from another page on the site. Check that both show the widget.

With spaMode on, the widget renders again after every client-side navigation: hash changes, back and forward, and route changes made with history.pushState or history.replaceState. Each time, it waits renderDelay milliseconds and renders if the brella-widget element is in the page.

If your framework inserts the page content after the route change, raise renderDelay, for example to 300.

You can also render at any time from your own code, for example when your component mounts:

window.brellaWidgetRender()

The function exists after the widget script has loaded.

Settings

Setting

What it does

Default

spaMode

Renders the widget again after client-side navigation. Must be the boolean true.

Off

renderDelay

Milliseconds to wait after a navigation before rendering.

0

window.brellaWidgetRender()

Renders the widget on demand.

—

Routing and deep links

  • The widgets don't use your site's router and don't add routes. Any URL that renders the brella-widget element works.

  • The schedule widget opens a session from the loaded day when the page URL has ?showSession=<session id>, and scrolls to the widget. Include the date parameter to target another day. It then removes the parameter from the URL without reloading.

  • The sponsors widget opens a booth when the page URL has ?showCompany=<sponsor id>, and scrolls to the widget.

  • The Share button in a session window copies the current page URL with the session parameters added. The sponsors widget shows Share in a booth window only when its showShareButton setting is true. Keep query parameters intact on the page that holds the widget, so shared links open the right session or booth.

Sizing

  • The widget container .brella-widget-root has a 16 px margin, 16 px padding, rounded corners and a white background. Override them in your stylesheet; colors and spacing are CSS variables such as --brella-widget-background and --brella-widget-padding-base.

  • The schedule widget grows with its content by default. Set "fixedHeight": true in the legacy settings and add style="height: 600px" to the div to make the widget fill that height and scroll inside it. Change the value to the height you want.

  • On windows 768 px wide or narrower, the schedule widget narrows the track column. The simplifiedOnMobile setting switches to the simplified layout at that width.

Limits

  • window.brellaWidgetOptions must be set before the widget script loads. Set after, it has no effect.

  • A self-hosted copy of the widget script works the same way. The data still comes from Brella's API, so your visitors' network must reach Brella.

  • You can embed several widgets on one page. Each one goes in its own div with the ID brella-widget. The schedule deep link scrolls to the first element with that ID, so if you use session links, put the schedule widget first.

Troubleshooting

The widget appears only after a full page reload
SPA mode is off, or window.brellaWidgetOptions is set after the widget script. Move the options line before the script line and check that spaMode is true (not "true").

The widget appears on some pages but not on others
The brella-widget element is added later than the render check. Raise renderDelay, or call window.brellaWidgetRender() when your component has mounted.

Join code is invalid.
The sponsors widget could not load the event or sponsors. Compare joinCode with Join code or URL slug in Details, then check whether the browser can reach Brella's API.

Related articles

Did this answer your question?