Headless SDK
@uxbee/umbraco-sdk-bynder (opens in a new tab) is a small TypeScript package for headless frontends, such as Next.js, Nuxt or Astro, that read Bynder assets from Umbraco's Content Delivery API (opens in a new tab).
The Bynder Asset Picker and File Picker return media in the same shape as Umbraco's own Media Picker, whether the editor picked a Bynder asset or an Umbraco Media item. The SDK turns that output into one typed object that's ready to render, so your frontend doesn't have to handle:
- single-select versus multi-select values (a single object or an array),
- relative Umbraco media URLs versus absolute Bynder URLs,
- alt text, copyright and subtitle tracks stored in
properties, - whether a Bynder video or audio asset may be played in an embedded player.
It has no runtime dependencies and works with any framework. It contains functions and types only, no UI components.
The SDK is included in your connector license. You don't need a separate license key, and the SDK doesn't check one.
Requirements
- An Umbraco site with the connector installed and the Content Delivery API enabled
- Node.js 20 or later. The package is ESM-only.
Install
npm install @uxbee/umbraco-sdk-bynderNormalize a picker value
Pass a picker property's value from a Delivery API response to normalizeMedia for a single value, or to normalizeMediaList for multiple values.
The optional second argument is your Umbraco site's URL. It's added in front of relative URLs, such as /media/... for Umbraco Media items. Absolute Bynder URLs are left unchanged.
import { normalizeMedia, normalizeMediaList } from "@uxbee/umbraco-sdk-bynder";
const UMBRACO_URL = "https://www.example.com";
const response = await fetch(`${UMBRACO_URL}/umbraco/delivery/api/v2/content/item/home`);
const page = await response.json();
// A single-select picker
const hero = normalizeMedia(page.properties.heroImage, UMBRACO_URL);
// A multi-select picker
const gallery = normalizeMediaList(page.properties.gallery, UMBRACO_URL);Both functions also accept the value of Umbraco's own Media Picker. You can switch a property between the Media Picker and a Bynder picker without changing your frontend.
normalizeMedia returns null when the property is empty. normalizeMediaList returns an empty array.
The normalized object
Every item is a NormalizedMedia:
| Property | Description |
|---|---|
id, name | The asset's id and name |
kind | "image", "video", "audio", "document" or "other" - use it to choose how to render the item |
url | The URL to render. For a video this is a playable video file, not a preview image |
alt | The alt text, or the asset's name when no alt text is set |
copyright | The copyright text, or null |
width, height, bytes | Dimensions and size when known, otherwise null |
extension, mediaType | The file extension and the Umbraco media type alias |
subtitle | A subtitle track (url, languageCode, languageText) from Transcript Sync for a File Picker video, or null |
canEmbedPlayer | Whether a video or audio item may be played in an <audio> or <video> element. Set by the Asset Picker; true for everything else |
properties | Every other value the connector returned, such as mapped metadata fields |
Render by kind
This React example renders each kind of media. The same logic works in any framework:
import type { NormalizedMedia } from "@uxbee/umbraco-sdk-bynder";
export function BynderMedia({ media }: { media: NormalizedMedia }) {
switch (media.kind) {
case "image":
return <img src={media.url} alt={media.alt} width={media.width ?? undefined} height={media.height ?? undefined} />;
case "video":
return media.canEmbedPlayer ? (
<video src={media.url} controls>
{media.subtitle && (
<track
kind="subtitles"
src={media.subtitle.url}
srcLang={media.subtitle.languageCode ?? undefined}
label={media.subtitle.languageText ?? undefined}
/>
)}
</video>
) : (
<a href={media.url}>{media.name}</a>
);
case "audio":
return media.canEmbedPlayer ? <audio src={media.url} controls /> : <a href={media.url}>{media.name}</a>;
default:
return <a href={media.url} download>{media.name}</a>;
}
}Video and audio
canEmbedPlayer is false for a Bynder video or audio asset that isn't marked Public in Bynder. Its URL can't be played directly by the browser, so link to it instead. Umbraco Media items are always embeddable.
Subtitles
Browsers only load a <track> file from the same origin as the page, or from a server that allows it through CORS. Subtitles from Transcript Sync are served by your Umbraco site. If your frontend runs on a different domain, route the subtitle file through your own frontend, for example with a small API route that fetches media.subtitle.url and returns it.
API reference
| Export | Description |
|---|---|
normalizeMedia(value, baseUrl?) | Normalizes a single picker value. Returns NormalizedMedia, or null when empty. Given an array, it returns the first item |
normalizeMediaList(value, baseUrl?) | Normalizes every item of a picker value, in order. Returns NormalizedMedia[] |
resolveMediaUrl(media, baseUrl?) | Returns the item's URL, with baseUrl added when the URL is relative |
getMediaKind(mediaType) | Maps a Delivery API mediaType to a MediaKind |
getAltText(media) | The alt text, or the item's name when no alt text is set |
getCopyright(media) | The copyright text, or null |
getCanEmbedPlayer(media) | Whether a video or audio item can be played in an embedded player |
getProperty(media, key) | Reads any other value from properties |
MediaPropertyKeys | The properties keys the connector sets |
Types: ApiMedia (one raw Delivery API media item), ApiMediaValue (a raw picker value), NormalizedMedia, MediaKind and SubtitleTrack.
Versions and compatibility
The SDK follows the connector's Delivery API output, not the Umbraco version, so its version numbers are independent of the NuGet package:
- A major SDK version is only released when that output changes in a breaking way.
- A minor version adds helpers, for example for a new property the connector starts returning.
- A patch version fixes a bug.
@uxbee/umbraco-sdk-bynder | Uxbee.Umbraco.Bynder | Umbraco |
|---|---|---|
| 1.x | 18.x | 18 |
| 1.x | 17.x | 17 |
Use connector 17.0.1 or later with the SDK. In 17.0.0, the File Picker's Delivery API could return a preview image as the url of a video, so a headless <video> showed a still image instead of playing.