Developers · Freedam Picker

Let people choose assets from Freedam inside your application

Add a “Choose from Freedam” button to a CMS, an e-commerce back office or an internal tool. People search the workspace and choose assets within their own access rights. Your page receives stable asset IDs and published URLs, ready to display.

Read the quickstart Open the playground

The snippet

One script and one function call

A workspace administrator creates an integration: the origins allowed to open the picker, the assets it offers and the publication channel of what it inserts. The Integrations page then gives you code like this, with the workspace host and the integration key filled in.

open() resolves with the chosen assets, or with null when the person cancels. Callbacks and DOM events report the same outcome for pages that prefer them.

Script tag

<script src="https://acme.freedam.io/sdk/picker/v1/picker.js"></script>
<button type="button" id="choose">Choose from Freedam</button>
<script>
  document.getElementById('choose').addEventListener('click', async () => {
    const assets = await Freedam.picker.open({
      workspace: 'acme.freedam.io',
      integration: 'w5r8n2c4t7bd',
    });
    if (assets) showImage(assets[0].url, assets[0].metadata.alt);
  });
</script>

Display modes

In a window, a tab, over your page or inside it

A single option, mode, sets the display, and every mode returns the same result. When the browser does not let the picker sign in inside your page, it continues in a window with the same options. The modal and inline modes need SDK version 1.1, the tab mode version 1.2.

mode: 'popup'

In a window

The default mode. The picker opens in a window on the workspace host. Sign-in, including single sign-on and passkeys, happens in a second window.

mode: 'tab'

In a new tab

The picker opens in a new browser tab, at full width. It keeps window.opener to send the selection to your page, then closes.

mode: 'modal'

Over your page

An iframe on a dimmed background, full screen on small screens, with the focus kept inside it until the person closes it.

mode: 'inline'

Inside your page

An iframe that fills an element you choose, such as a side panel of your editor, at least 480 pixels high.

What your page receives

One object per asset, with URLs ready to use

url: The asset in the format the person chose, on a public URL of the integration’s publication channel.
url_template: The same signed URL with {options} in place of the size: build any width, crop or file format without calling Freedam. widths lists the widths it serves, for a srcset.
focus_point: Where the subject is, in percent, ready for object-position when your layout crops the image.
metadata: The fields the integration exposes, such as the title, the alt text and the credit, within what the person may see.
player_url: For videos: the player with the settings chosen in the picker, its embed code and the HLS stream.
usage_token: Declares the page that shows the asset, so the workspace sees where each asset is used.

Images, videos and documents each have their own fields. The reference lists them all, with the JSON Schema of the payload.

An image, shortened

{
  "gaid": "IM-20260309-UDXZH8PP6VPW",
  "type": "image",
  "url": "https://acme.freedam.io/i/w=2048,fmt=hero/IM-…",
  "url_template": "https://acme.freedam.io/i/{options}/IM-…",
  "widths": [128, 256, 512, 1024, 2048],
  "focus_point": { "x": 45.2, "y": 38.7 },
  "metadata": {
    "title": "Head office, Lyon",
    "alt": "Glass front at sunset",
    "credit": "Studio Martin"
  },
  "usage_id": "9d4e1f3a-6b2c-4f8e-a1d7-3c5b9e2f0a64",
  "usage_token": "fdu_…",
  "choice": { "format": "hero", "file_format": null }
}

npm and web component

Load it the way your application is built

The same SDK comes as the npm package @freedam/picker, and the script also defines a <freedam-picker> element for pages where you do not want to write JavaScript. The quickstart has React and Vue examples.

npm install @freedam/picker

import { open } from '@freedam/picker';

const assets = await open({
  workspace,
  integration,
  select: 'multiple',
  types: ['image', 'video'],
});

<freedam-picker workspace="acme.freedam.io" integration="w5r8n2c4t7bd">
  <button type="button">Choose from Freedam</button>
</freedam-picker>

Versions

Updates without a code change, or a pinned release

/sdk/picker/v1/picker.js
The latest 1.x version. The snippet of the Integrations page uses it.
/sdk/picker/{version}/picker.js
One exact version, whose file never changes. Load it with its integrity value, listed in the reference.
protocol=1
The messages between the picker and your page have their own version. Freedam keeps accepting a previous version for at least six months.

What the picker takes care of

Allowed origins

The picker opens only from the origins the integration lists, and sends the selection to that exact origin, never to any other page.

Each person’s access rights

People see the assets they may view in Freedam, within the integration’s rules. Visitors without an account can choose assets too, when an administrator turns that access on.

No token on your page

Your page loads a script and calls one function. It holds no API token: the picker runs on the workspace host and acts for the person using it.

Published URLs

Inserted assets are published on a channel of the workspace. Their URLs stay valid until the asset is unpublished or its usage rights end.

Served by your workspace

The script comes from the workspace host, with no third-party CDN. A versioned URL with a Subresource Integrity value pins an exact release.

Small and typed

A few kilobytes, no runtime dependency, TypeScript types and a JSON Schema for the payload. Versions follow semantic versioning.

Developers · Freedam Picker

Try the picker with your own options

The playground opens the picker on a demo workspace, writes the code for the options you choose and shows the payload your page would receive.

Open the playground Read the reference