File URL Formatter

Overview

Every image URL rendered inside a FilePicker component in the Webiny admin UI — thumbnails in the Headless CMS field editor, the Website Builder file input, and any custom field that uses FilePicker — passes through the FileUrlFormatter extension point before being displayed.

The default formatter (registered by the File Manager app) appends ?width=128 to the URL so thumbnails are served at a sensible size. You can replace this behaviour entirely: remap the width parameter to your CDN’s own syntax, add authentication tokens, rewrite the host, or apply any other transformation your image delivery pipeline requires.

Implement the Formatter

Create a class that implements FileUrlFormatter.Interface. The single required method is format(url: URL, params?: FileUrlFormatter.Params): void. Mutate the url object in place — no return value is expected.

params carries the caller’s intent. The width key is the only built-in parameter; any additional keys you pass when calling format are forwarded as-is and your implementation can act on them.

Register the Formatter

Wrap the implementation in a feature and mount it with RegisterFeature:

Then add the extension to your webiny.config.tsx:

How It Works

When Webiny boots it resolves the active FileUrlFormatter from the DI container and makes it available throughout the admin UI via AdminUiProvider. The FilePicker component’s presenter applies format(url, { width: 128 }) when building its view model, so the formatted URL is already in place before any render component sees it.

Type Reference

All types are accessed through the FileUrlFormatter namespace — no direct imports from internal packages needed.

Full Example — ReplacingwidthWith a CDN-Specific Parameter