Files SDK

The Files SDK adds Fluid’s Digital Asset Management (DAM) picker to your application. You can let users browse approved assets, upload files, import a public URL, search Unsplash, or generate an image with AI. The package works with vanilla JavaScript and includes React bindings.

Install the SDK

npm install @fluid-app/dam-picker

pnpm add @fluid-app/dam-picker

yarn add @fluid-app/dam-picker

Choose an asset

Create one picker instance, then call open() in response to a user action.

import { DamPicker } from "@fluid-app/dam-picker";

const picker = new DamPicker({
  token: "pub-acme-wellness-assets",
  shopName: "acme-wellness",
  accept: ["image/*"],
  maxFiles: 1,
  onSelect: (result) => {
    const image = result.asset;
    document.querySelector("#hero-image").src = image.url;
  },
  onCancel: () => {
    console.log("Asset selection cancelled");
  },
  onError: (error) => {
    console.error(error.code, error.message);
  },
});

document.querySelector("#choose-image").addEventListener("click", () => {
  picker.open();
});

For browser integrations outside Fluid Admin, pass a public (pub-) token and the company’s shop name. Do not put a company or partner token in client-side code. See Authentication for token guidance.

Configure the picker

Use these options to shape the selection workflow.

Option	Purpose
`accept`	Restrict files by MIME type or extension, such as `["image/*", ".pdf"]`.
`fromSources`	Choose which source tabs appear.
`maxFiles`	Limit how many files a user can select or upload. The default is `1`.
`minFiles`	Require a minimum number of selections. The default is `1`.
`maxSize`	Set the maximum size of each file in megabytes.
`imageDim`	Require exact image dimensions as `[width, height]`.
`imageMin`	Require minimum image dimensions as `[width, height]`.
`imageMax`	Require maximum image dimensions as `[width, height]`.
`transformations`	Show selected transformation tools, or use `false` to skip transformations.
`onSelect`	Receive the confirmed asset selection.
`onCancel`	Handle the user closing the picker without a selection.
`onError`	Handle authentication, network, validation, and upload errors.

Select sources

The SDK supports five source identifiers:

local_file_system
url
dam_library
unsplash
ai_generate

For example, you can limit an editor to uploads and the approved DAM library:

const picker = new DamPicker({
  token: "pub-acme-wellness-assets",
  shopName: "acme-wellness",
  fromSources: ["local_file_system", "dam_library"],
  accept: ["image/*"],
  maxFiles: 5,
  onSelect: (result) => {
    renderGallery(result.assets);
  },
});

Configure transformations

All available transformation tools are enabled by default. Set individual tools to false when a workflow should offer fewer choices.

const picker = new DamPicker({
  token: "pub-acme-wellness-assets",
  shopName: "acme-wellness",
  accept: ["image/*"],
  transformations: {
    crop: true,
    rotate: true,
    quality: true,
    removeBackground: true,
    changeBackground: false,
    upscale: false,
    retouch: false,
    dropShadow: false,
    smartCrop: true,
    editWithAi: false,
  },
  onSelect: ({ asset }) => {
    updateProductImage(asset.url);
  },
});

Set transformations: false for files that should be returned without an editing step.

Use the selection result

onSelect receives a result with two views of the selection:

result.asset is the first selected asset.
result.assets is every selected asset and is always an array.

Each selected asset includes its public url, assetCode, name, and mimeType. It can also include dimensions, file size, a variant identifier, and a numeric DAM identifier.

import type { DamPickerResult } from "@fluid-app/dam-picker";

function saveSelection(result: DamPickerResult) {
  const records = result.assets.map((asset) => ({
    assetCode: asset.assetCode,
    url: asset.url,
    mimeType: asset.mimeType,
    width: asset.metadata?.width,
    height: asset.metadata?.height,
  }));

  saveAssets(records);
}

Store the assetCode with the URL when you need a stable DAM identity as well as a renderable asset location.

Open an existing asset for editing

Pass asset to skip source selection and open one existing asset in the transformation editor. You can identify it by its DAM asset code.

const editor = new DamPicker({
  token: "pub-acme-wellness-assets",
  shopName: "acme-wellness",
  asset: { assetCode: "hero-summer-2026" },
  onSelect: ({ asset }) => {
    updateHeroImage(asset.url);
  },
});

editor.open();

You can also pass an asset URL, or both the URL and asset code.

Use the React hook

Import React bindings from @fluid-app/dam-picker/react. The hook returns an open() function and the current open state.

import { useState } from "react";
import { useDamPicker } from "@fluid-app/dam-picker/react";

export function ImageSelector() {
  const [imageUrl, setImageUrl] = useState<string>();
  const { open, isOpen } = useDamPicker({
    token: "pub-acme-wellness-assets",
    shopName: "acme-wellness",
    accept: ["image/*"],
    maxFiles: 1,
  });

  return (
    <div>
      <button
        disabled={isOpen}
        onClick={() =>
          open({
            onSelect: ({ asset }) => setImageUrl(asset.url),
          })
        }
      >
        Choose image
      </button>

      {imageUrl && <img src={imageUrl} alt="Selected product" />}
    </div>
  );
}

For declarative control, import DamPickerModal from the same React entry point.

Clean up an instance

Call destroy() when the component or view that owns a vanilla JavaScript picker is removed.

picker.destroy();

This closes the picker and removes the resources associated with that instance.

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Portal & Widgets

Files SDK

Install the SDK

Choose an asset

Configure the picker

Select sources

Configure transformations

Use the selection result

Open an existing asset for editing

Use the React hook

Clean up an instance

​Install the SDK

​Choose an asset

​Configure the picker

​Select sources

​Configure transformations

​Use the selection result

​Open an existing asset for editing

​Use the React hook

​Clean up an instance

Install the SDK

Choose an asset

Configure the picker

Select sources

Configure transformations

Use the selection result

Open an existing asset for editing

Use the React hook

Clean up an instance