Umbraco Connector
Headless SDK

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

Terminal
npm install @uxbee/umbraco-sdk-bynder

Normalize 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.

lib/page.ts
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:

PropertyDescription
id, nameThe asset's id and name
kind"image", "video", "audio", "document" or "other" - use it to choose how to render the item
urlThe URL to render. For a video this is a playable video file, not a preview image
altThe alt text, or the asset's name when no alt text is set
copyrightThe copyright text, or null
width, height, bytesDimensions and size when known, otherwise null
extension, mediaTypeThe file extension and the Umbraco media type alias
subtitleA subtitle track (url, languageCode, languageText) from Transcript Sync for a File Picker video, or null
canEmbedPlayerWhether a video or audio item may be played in an <audio> or <video> element. Set by the Asset Picker; true for everything else
propertiesEvery 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:

components/BynderMedia.tsx
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

ExportDescription
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
MediaPropertyKeysThe 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-bynderUxbee.Umbraco.BynderUmbraco
1.x18.x18
1.x17.x17
⚠️

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.