Bynder

The Bynder app adds a field type for browsing, searching, and selecting assets from a Bynder portal without leaving the Visual Editor. Asset metadata and transformation URLs are part of the Content Delivery API response.

Features

• Browse and search assets and collections from a Bynder portal.
• Filter by tag and file type, and sort by name or date.
• Select a single asset or multiple assets, depending on the field configuration.
• Apply image transformations such as format, quality, and focus points.

Setup

In the Block Library, select the block you want to edit, add a field, set its field type to Plugin, and set the custom type to storyblok-bynder. Learn more about blocks and fields.

The field takes the following options, all optional:

Option	Description
accessToken	Permanent Bynder access token. Requires portalDomain. Grant the asset:read and meta.assetbank:read permissions for assets, and collection:read for collections.
portalDomain	Domain of the Bynder portal editors authenticate to, for example my-company.bynder.com. Without this option, editors can specify any portal. Required when you set accessToken.
assetTypes	JSON array of the asset types editors can select, for example ["VIDEO", "IMAGE"]. Accepts AUDIO, DOCUMENT, IMAGE, VIDEO, and ARCHIVE. Without this option, editors can select any file format.
multiple	Set to true to allow selecting more than one asset. Any other value, or no value, limits the field to a single asset.
hideLimitedUse	Set to true to hide assets marked as limited use. Any other value, or no value, disables the option.
defaultSearchTerm	Default value of the asset search field.

In the Visual Editor, open a block with a Bynder field and select Add Asset. Log in to a Bynder portal, or use the configured portal. Select one or more assets, select Add asset in the lower-right corner of the modal, and save or publish the story.

Transformations

Transformations let editors control the output format and quality of an image asset, set focus points, and more. Transformations require the Dynamic Asset Transformations(DAT) feature in Bynder and are available for single assets only—setting multiple to true disables them.

To add a transformation to an image asset:

1. Hover over the asset thumbnail, open the three-dot menu in its upper-left corner, and select New transformation.
2. Set the format and quality under Output options.
3. Select Add transformation and configure the transformation. For example, to set a focus point, choose Fill, select Override focus point, and enable Show real time editor. Then drag the focus point in the image preview and fine-tune the position with the XY percentages.
4. Select Apply transformations.

In the select field next to Add asset, choose the custom transformation or one of Bynder’s default transformations.

API response

The stories endpoint of the Content Delivery API returns the following data for a Bynder field. The files object includes the default transformations and a base URL when the Bynder portal has transformations enabled. The selectedFile property holds the selected asset variant.

[
  {
    "id": "KEFzc2V0X2lkIDJEQzUyRTYyLTVGQjEtNDkzOC1CRjY4OTg1N0VGOUI1MUUyKQ==", // The Bynder asset ID
    "name": "Earth", // The Bynder asset name
    "files": {
      "transformBaseUrl": "https://datdemo.getbynder.com/transform/fb60f96f-ebf2-4a69-9ed8-8a828ef17283/earth.jpg", // The Bynder asset base URL
      "thumbnail": {
        "url": "https://storyblok.bynder.com/m/2c3ed2b262cde983/thul-earth.jpg",
        "width": 250,
        "height": 250,
      },
      "mini": {
        "url": "https://storyblok.bynder.com/m/2c3ed2b262cde983/mini-earth.jpg",
        "width": 80,
        "height": 80,
      },
    },
    "databaseId": "2DC52E62-5FB1-4938-BF689857EF9B51E2", // The Bynder database ID
    "description": "The Earth is our home planet.", // The Bynder asset description
    "selectedFile": {
      "url": "https://storyblok.bynder.com/transform/95cc6c36-61a9-48a9-9caf-0b63dbd7dfe7/earth?io=transform:fill&focuspoint=0.25,0.3", // The currently selected Bynder asset variant; in this case, the custom transformation URL
    },
  },
]

The files.transformBaseUrl property is present only when enabling Bynder’s DAT feature.

Further resources

Storyblok on the Bynder marketplace

Bynder in the app directory