Quickstart

We will put a live trail list on a page. The other three embeds work exactly the same way — only the element name and its options change.

Create a publishable key

In the Ullr dashboard, open Integrations → API keys and create a key:

Type: Publishable
Scopes: the “All embeds” preset, or just trails:read and resorts:read for this example
Allowed domains: your website’s hostname, e.g. example.com. Add *.example.com too if you serve from subdomains. You do not need to add localhost — it is always allowed.

Copy the key. It looks like 1a2b3c4d5e6f.aVeryLongRandomString.

Publishable keys stay visible in the dashboard, so you can come back and copy the snippet again later. Secret keys are shown once — and are not what you want here.

Find your area id

It is in the dashboard URL when you have your area selected, or ask support. Area ids are stable, so it is fine to paste it straight into your page.

Add the script and the element

Paste this into your page’s HTML, replacing the key and area id:

conditions.html


<script type="module" src="https://widget.ullr.ski/web-components/ullr-trail-list.js"></script>
 
<ullr-trail-list
  apiKey="1a2b3c4d5e6f.aVeryLongRandomString"
  areaId="your-area-id"
  sport="SNOW"
  visibleColumns="status,name,surface,length"
  units="imperial"
></ullr-trail-list>

The script tag can go in <head> or next to the element — it is a module, so it does not block rendering either way.

Load the page

You should see your trails with their current status. If you get a blank space instead, open the browser console: the element logs a clear message when the key or area id is missing, and the network tab will show a 401 or 403 if the key is wrong or the domain is not allowed. Troubleshooting covers each case.

Adding a second embed

Every embed is independent. To add the lift list underneath, include its script too:


<script type="module" src="https://widget.ullr.ski/web-components/ullr-trail-list.js"></script>
<script type="module" src="https://widget.ullr.ski/web-components/ullr-lift-list.js"></script>
 
<ullr-trail-list apiKey="…" areaId="…" sport="SNOW"></ullr-trail-list>
<ullr-lift-list  apiKey="…" areaId="…" sport="SNOW"></ullr-lift-list>

Both scripts share their common code, so the second one is a small download.

Using an embed in React

The elements are standard custom elements, so React renders them directly. Two things to watch:


import { useEffect } from 'react';
 
export function TrailStatus() {
  useEffect(() => {
    // Load the bundle once, on the client.
    const script = document.createElement('script');
    script.type = 'module';
    script.src = 'https://widget.ullr.ski/web-components/ullr-trail-list.js';
    document.head.appendChild(script);
  }, []);
 
  return (
    <ullr-trail-list
      apiKey={process.env.NEXT_PUBLIC_ULLR_PUBLISHABLE_KEY}
      areaId="your-area-id"
      sport="SNOW"
    />
  );
}

In TypeScript, declare the element so JSX accepts it:

ullr-elements.d.ts


declare namespace JSX {
  interface IntrinsicElements {
    'ullr-trail-list': React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & Record<string, unknown>,
      HTMLElement
    >;
  }
}

Because attributes are read once at mount, changing a prop will not update the element. Give it a key that changes when the configuration changes, so React remounts it:
```
<ullr-trail-list key={`${sport}-${units}`} sport={sport} units={units} … />
```

Next steps

Tune the appearance: each embed’s page lists every attribute.
Put it on a TV: see TVs & kiosks.
Match your brand: pass theme="#RRGGBB".