Media Library beta

Strapi has completely reworked the Media Library UI. This page describes the reworked UI, which is available as a beta feature 5.52.2+ behind the betaMediaLibrary future flag, before it becomes the default UI.

Read the Media Library page for how to enable the flag, and for every configuration option, which the flag does not change.

Usage betaMediaLibraryThis feature requires the betaMediaLibrary feature flag to be enabled.

Path to use the feature: Media Library

The Media Library displays all assets uploaded in the application, either via the Media Library itself or via the Content Manager when managing a media field.

Assets uploaded to the Media Library can be inserted into content-types using the Content Manager.

Note

The Media Library hides what your role cannot do instead of displaying a disabled control. With the Access the Media Library permission alone, the library is read-only: there is no New button, no selection checkbox and no bulk action, and the fields of the asset details panel cannot be edited. See Users & Permissions to grant the Create, Update, Download and Copy link permissions of the Upload plugin.

Interface overview

The Media Library is organized in the following areas:

• The folder tree 1 on the left lists Home and the full folder hierarchy (see navigating folders).
• The page title 2 names the location you are currently browsing, either Home or a folder name, followed by the number of files it holds directly, displayed as, for instance, 11 items. Subfolders and their content are not counted, and the number does not change when filters are active.
• The New button 3 creates a folder or uploads assets (see adding assets and adding folders).
• The toolbar 4 spans the row above the list. Use it to filter, search and sort the list (see finding assets), and to switch between the grid view and the table view (see switching views).
• The list 5 displays the folders and assets of the current location. More assets load as you scroll.

A Beta notice sits above the list and reminds you that some features are still in progress. Click Close to dismiss it: it stays dismissed in that browser.

Each folder and asset in the list has a checkbox to select it (see selecting items) and a button (see using the item actions menu). The Media Library calls a folder or an asset an item, and several controls use that word.

What changed from the previous Media Library

In the previous UI	In the Media Library beta
Add new assets and Add new folder buttons	A single New button that does both (see adding assets)
Breadcrumbs above the list	A folder tree on the left (see navigating folders)
Folder cards displaying how many items they hold	Folder names only. To know how many assets a folder holds directly, open it and read the page title
Pagination, with an Entries per page setting	No pagination: more assets load as you scroll
A button to configure the view	No view configuration (see configuring the view)
A button opening a search field	A search field always displayed in the toolbar (see searching assets)
A Details window that covers the library	A details panel that leaves the list usable (see managing individual assets)
A crop mode and a focal point mode, opened separately	A single Crop & Focus area editor (see cropping images and setting a focus area)

Note

The Media Library stores what you are looking at in the page URL: the current folder, the search term, the filters, the sort order, where folders are displayed, and the open asset. Copying the URL and sharing it with another user of the same Strapi project gives them the same list. The grid or table choice is not part of the URL, and a filter set to a relative date is resolved again when the URL is opened.

Switching views

The list displays either as a grid of cards or as a table. Click Grid view or Table view in the toolbar to switch. Your choice is remembered in your browser for the next visit.

The table view displays a Name, Creation date, Last modified and Size column for each item, along with a Select all checkbox in the header row. Assets missing a caption or an alternative text are flagged with a warning icon.

Note

Column headers in the table view are labels, not sort controls. Use the toolbar's Sort menu to change the order (see sorting assets).

Navigating folders

The folder tree on the left side of the interface lists the whole folder hierarchy. There is no breadcrumb: the tree and the page title tell you where you are.

• Click a folder name, in the tree or in the list, to display its content.
• Click the button next to a folder name to expand or collapse its subfolders.
• Click Home to go back to the root of the library.

Strapi does not enforce a maximum folder depth. The folder tree expands automatically to reveal the folder you are browsing.

Using the item actions menu

The button of an asset or a folder opens a menu that acts on that item only, whatever else is selected in the list.

On an asset, the menu offers:

• Replace media
• Copy link to media
• Download media
• Move to folder
• Delete

On a folder, it offers:

• Copy link to folder
• Rename folder
• Move to folder
• Delete folder

Using the right-click menu

Right-clicking the empty parts of the Media Library opens a menu with the same creation actions as the New button. They act on the folder you are currently browsing:

• New folder
• File upload
• File upload from URL

The menu opens anywhere in the scrolling column: the list, the empty space below the last row, the page header band beside the title, and the padding around them. It behaves the same in the grid view and in the table view, and is dismissed with Escape or a click elsewhere.

Anything you can interact with keeps your browser's own menu instead, so copying and pasting still works in the search field. This covers the New button, search, filters, sorting, the view toggle and the filter badges, as well as asset cards, folder cards, table rows and the column header row of the table view.

Note

The menu requires the Create permission of the Upload plugin. Without it, right-clicking the library falls through to your browser's menu with nothing offered. See Users & Permissions.

Adding assets

Media types the Media Library previews

Media type	Extensions
Image	- JPEG - PNG - GIF - SVG - TIFF - ICO - DVU
Video	- MPEG - MP4 - MOV (Quicktime) - WMV - AVI - FLV
Audio	- MP3 - WAV - OGG
File	- CSV - ZIP - PDF - XLS, XLSX - JSON

The Media Library itself does not restrict file types. Which files are accepted is decided by the security.allowedTypes and security.deniedTypes options (see security) and by the maximum file size (see max file size). SVG files are denied by default in projects generated with Strapi 5.52.2+ and later (see SVG uploads).

Assets are always uploaded to the location you are currently browsing. Navigate to the target folder before uploading, or move the assets afterwards (see moving assets and folders).

In an empty folder, and in a new project, the list is replaced by a No assets yet message with an Add assets button that opens the same file browser as New > File upload.

There are 3 ways to add assets.

Uploading files from your computer

1. Click the New button in the upper right corner of the Media Library.
2. Click File upload.
3. Select one or several files in your system's file browser and confirm.

The upload starts immediately and its progress is reported in the upload dialog (see following upload progress).

Uploading files by drag and drop

1. Drag one or several files from your computer onto the Media Library.
2. Check the destination folder named in the Drop here to upload to overlay.
3. Release the files.

Caution

Files dropped from your computer always land in the folder you are currently browsing, whatever they are dropped on. Dropping a file on a folder card does not upload it into that folder: navigate into the folder first. Dragging an item that is already in the library onto a folder does move it (see moving assets and folders).

Uploading files from a URL

1. Click the New button in the upper right corner of the Media Library.
2. Click File upload from URL.
3. In the URL(s) field of the Import from URL dialog, type or paste up to 20 URLs, one per line.
4. Click Upload.

Strapi downloads each file server-side and adds it to the current folder. The server reports no incremental byte count for this flow, so the upload dialog displays a moving progress bar without a percentage.

Caution

URLs must use the http or https protocol, and must resolve to a publicly reachable address. URLs that resolve to a private or internal address, such as localhost or an address on your own network, are rejected to prevent server-side request forgery.

Following upload progress

Uploads are reported in a dialog that lists every file of the batch with its own status, such as Queued, Uploading... or Uploaded. The dialog is available throughout the admin panel, not only in the Media Library, so you can navigate to another part of Strapi while a batch uploads.

The dialog can be minimized to a summary line and maximized again. It offers a Cancel all button that stops the batch while keeping the files already uploaded, a Retry button that restarts the files you cancelled, and a Close button once the batch is finished. Dropping more files while a batch is running adds them to that batch.

Caution

Retry is only displayed after a cancellation, and it only restarts cancelled files. A file that failed on its own cannot be retried from the dialog: read the reason on its row, fix the cause, and upload it again.

By default, files are uploaded one at a time. Increase concurrentUploadRequests to upload several files in parallel.

Automatically generating metadata with Strapi AI

GrowthThis feature is available with a Growth plan.

When enabled, Strapi AI automatically generates an alternative text and a caption for images uploaded to the Media Library, helping you improve content accessibility and SEO. The upload dialog reports the outcome for each file, such as Uploaded • Metadata generated or Upload complete • Metadata generation skipped.

AI metadata generation only works with PNG, JPEG, WebP, HEIC and HEIF images. Every other file, including GIF, SVG and TIFF images, is reported as skipped. The feature is enabled by default, but can be disabled in the Media Library settings if needed.

Metadata can also be generated for images that already exist in the library, either from the Media Library settings for every image that lacks one, or with the Create metadata bulk action for a specific selection (see generating metadata in bulk).

Strapi AI credits

Strapi AI includes 1,000 credits per month on the Growth plan, and 10 free credits during the free trial. Strapi AI is not available on Enterprise plans.

Lightweight actions use fewer credits, while more complex ones use more.

You can check your credit usage in the Settings Overview of the admin panel. Notifications are sent when your usage reaches 80%, 90%, and 100% of your monthly allowance. Overages apply.

Credits are shared across all users within the same project instance.

When your credits run out, you can keep using Strapi AI, with overages billed monthly. For more information about Strapi AI, please refer to the dedicated support article.

Finding assets

The toolbar offers a Filter button, a Search field and a Sort button, in that order. Search looks across the whole library, while filters and sorting apply to the location you are browsing.

Searching assets

Type in the toolbar's Search field to find assets and folders by name.

The search covers the whole library, not only the folder you are browsing, and it returns both folders and assets. The page title becomes Search results for "your term" followed by the number of folders and assets found.

To leave the search, click the Clear button inside the search field, or navigate to a folder in the folder tree.

When a search returns nothing, the list is replaced by a No results found message with a Clear search button.

Filtering assets

3 filter fields are available to narrow the list:

Filter field	Values	Conditions
Type	Folder, Picture, Audio, Video, Document	is, is not
Creation date	A relative preset, from 1 day ago to 1 year ago	is exactly, within the last, not within the last
Creation date	A custom date range	is, is not
Last modified	A relative preset, from 1 day ago to 1 year ago	is exactly, within the last, not within the last

To filter the list:

1. Click the Filter button in the toolbar.
2. Click a filter field.
3. Click one or several values. The Type list stays open so that you can check several types, and the badge lists them all, for instance Type is Picture, Video.
4. (optional) Repeat for another field.

Filters combine, so only the items matching every filter are displayed. Each applied filter is added below the toolbar as a badge. Click the condition or the value segment of a badge to change it, and the button to remove that filter.

Note

Filters apply to the location you are browsing, not to the whole library. Use the search to look across all folders.

A Type badge also decides whether folders are displayed: folders are hidden unless Folder is one of its values, and assets are hidden when Folder is its only value.

When the active filters match nothing, the list is replaced by a No items matched current filters message with a Clear filters button that removes all of them. There is no clear-all control in the toolbar: as long as the filters match something, remove the badges one by one.

Sorting assets

Click the Sort button in the toolbar to change the order of the list. The button label always names the active rule, for instance Sort: Most recent updates.

The Sort section offers 6 mutually exclusive rules: Oldest uploads, Most recent updates (the default), A to Z, Z to A, File size ascending, and File size descending.

In the table view, an additional Folders section decides whether folders are grouped On top, which is the default, or Mixed with files, in which case they follow the active sort rule. The grid view always groups folders on top, so it does not display that section.

Note

Folders follow the active sort rule when it can apply to them: Oldest uploads orders them by their own creation date, and A to Z and Z to A by name. They stay in alphabetical order for the default Most recent updates rule, and for the 2 file size rules because folders have no size.

Managing individual assets

Click an asset in the list to open its details panel on the right side of the interface. The list stays visible and usable behind the panel.

The panel is organized as follows:

• A preview of the asset. Images are displayed, videos and audio files can be played with the browser's own controls, and PDFs are rendered inline. Any other file type displays its icon and No preview available. Images also get a Crop button (see cropping images and setting a focus area).
• A read-only File info section listing the Creation date, Last updated, Created by, Size, Dimensions (images only), Extension and Asset ID of the asset.
• The editable File name, Location, Caption and Alternative text fields. A caption and an alternative text can be set on any file type, not only images, and a warning is displayed next to each of the 2 fields when it is empty.
• A row of icon-only buttons at the bottom: Delete this file, Copy link, Download and Replace this file, next to the Save changes button.

Editing an asset name, caption and alternative text

To rename an asset, or to add or change its caption and alternative text:

1. Click the asset in the list.
2. Update the File name, Caption or Alternative text fields.
3. Click Save changes.

Note

Save changes stays disabled until you change something, and an empty File name prevents saving. If you close the panel with unsaved changes, Strapi asks you to confirm before discarding them.

Tip

The Location field of the same panel moves a single asset to another folder. See moving assets and folders for the other options.

Cropping images and setting a focus area

One editor handles both cropping and the focus area. The focus area, also called focal point, keeps the most important part of an image visible when your front end crops or resizes it.

1. Click an image in the list to open its details panel.
2. Click the Crop button on the preview. The Crop & Focus area editor opens.
3. Define the crop area by dragging the handles in the corners of the rectangle, or by typing exact values in the width and height fields of the editor panel.
4. (optional) Click the Lock aspect ratio button to resize both dimensions together.
5. Define the focus area by dragging the circle inside the crop rectangle, or by typing exact values in the X and Y fields.
6. Save your changes:
   • Click Apply to crop the original asset. The asset keeps its ID, so content already using it is updated.
   • Click Save as copy to keep the original untouched and create a new asset in the same folder. The copy inherits the caption and the alternative text of the original.

To leave the editor without changing anything, click Cancel.

Note

The focus area is stored on the asset and returned by the API as a focalPoint value, so your front end can use it when it crops or resizes the image.

Note

The numeric fields are hidden on small screens. Set the crop and focus areas by dragging the rectangle and the circle directly on the image instead.

Replacing an asset file

Replacing swaps the file behind an asset while keeping the asset itself, so every content entry already pointing at it keeps working.

1. Click the asset in the list to open its details panel.
2. Click the Replace this file button.
3. Click Continue in the confirmation dialog.
4. Select the new file in your system's file browser and confirm. The file browser only offers files whose type matches the current asset.

Warning

The previous file is permanently replaced and cannot be recovered. If AI metadata generation is enabled, Strapi also generates a new caption and alternative text for the replacement file, overwriting the existing ones. The confirmation dialog says so before you continue.

Downloading assets and copying links

1. Click the asset in the list to open its details panel.
2. Click the Download button to save the file to your computer, or the Copy link button to copy its URL to the clipboard.

Both actions are also available from the asset's actions menu, as Download media and Copy link to media.

Note

Copy link to media copies the asset's own URL, the one your front end uses to serve the file. Copy link to folder, in a folder's actions menu, copies a link to that folder in the admin panel, which only works for someone logged into Strapi.

Deleting assets

1. Click the asset in the list to open its details panel.
2. Click the Delete this file button.
3. Click Confirm.

Warning

Deleted files cannot be recovered. If a file is currently in use, the linked content breaks and image containers are left empty.

Assets can also be deleted in bulk, together with folders (see deleting items in bulk).

Using bulk actions

Bulk actions apply to a selection of assets and folders. Select the items first, then pick an action in the bulk actions bar.

Selecting items

Click the checkbox of a folder or an asset to select it. Assets and folders can be selected together.

The following shortcuts speed up selection:

Shortcut	Description
Cmd/Ctrl + click	Adds an item to the selection or removes it.
Shift + click	Selects every item between the last selected item and the clicked one.
Space	With a card or a row focused, adds it to the selection or removes it.
Enter	With a card or a row focused, opens the asset details panel, or enters the folder.

Both modifier shortcuts work on the card or the row itself. Clicking the file name always opens the details panel, whatever modifier you hold.

In the table view, a Select all checkbox in the header row selects every item currently displayed, and empties the selection when everything is already selected.

Selecting an item displays the bulk actions bar at the bottom of the interface. The bar reports how many items are selected and offers the bulk actions. Click Clear selection to empty the selection.

In the grid view as well as the table view, the bar also offers a Select all button 5.52.3+ that selects every folder and asset currently displayed. Only the items already loaded are selected: scroll further down the list, then click Select all again to add the newly loaded items. Unlike the checkbox of the table view header, the button does not empty the selection when everything is already selected.

Note

The selection survives switching between the grid and the table view, but it is emptied when you navigate to another folder or change the search, the filters or the sort order.

Opening an asset details panel hides the bar while the panel is open. The selection is kept and the bar comes back when you close the panel.

Moving items in bulk

1. Select the assets and folders to move.
2. Click the Move button in the bulk actions bar.
3. In the Move elements to dialog, select the destination in the Location list. The root of the library is listed there as Media Library, and folders carry their full path, for instance Brand assets / Logos. The folder the items already sit in, and any folder they cannot be moved into, are not listed.
4. Click Move.

Items can also be moved by drag and drop (see moving assets and folders).

Deleting items in bulk

1. Select the assets and folders to delete.
2. Click the Delete button in the bulk actions bar.
3. Click Confirm in the dialog.

Warning

Deleting a folder also deletes everything it contains, including its subfolders and their assets. None of it can be recovered.

Generating metadata in bulk

GrowthThis feature is available with a Growth plan.

When Strapi AI is enabled, a Create metadata button in the bulk actions bar generates a caption and an alternative text for the selected images.

1. Select the images to describe.
2. Click the Create metadata button in the bulk actions bar.

Metadata can be generated for up to 40 assets at a time. Only PNG, JPEG, WebP, HEIC and HEIF images are supported: selected folders are ignored, and selected files of any other type are reported as skipped.

Organizing assets with folders

Folders in the Media Library help you organize uploaded assets. From the Media Library, it is possible to create new folders, move assets and folders, rename a folder, and delete folders. To browse them, see navigating folders.

Note

Folders follow the permission system of assets (see Users & Permissions feature). It is not yet possible to define specific permissions for a folder. Creating a folder requires the Create permission on assets, and renaming, moving or deleting one requires the Update permission.

Caution

In this beta, Rename folder, Move to folder and Delete folder are displayed to every user who can see the folder, including users without the Update permission on assets. The action is then refused by the server.

Adding folders

1. Navigate to the location where the folder must be created.
2. Click the New button in the upper right corner of the Media Library.
3. Click New folder.
4. Type a name in the Folder name field.
5. Click Create folder.

Note

The dialog title names the parent folder, for instance New folder in Home. To create the folder somewhere else, cancel, navigate to the intended parent, and start again.

Moving assets and folders

Assets and folders can be moved in 3 ways:

• By drag and drop, for a few items at a time. Drag an asset or a folder onto a folder in the list, or onto a folder of the folder tree, including Home. Hovering a folder of the tree for a moment expands it, so that you can drop items into a subfolder in one gesture. Dragging one item of a selection moves the whole selection.
• With the Move elements to dialog, for many items at once (see moving items in bulk). It is also available for a single item, as Move to folder in its actions menu.
• From the details panel of an asset, by changing its Location field (see managing individual assets).

Note

A folder cannot be moved into itself or into one of its own subfolders. Invalid destinations are refused while you drag.

Tip

Drag and drop uses the pointer. To move items with the keyboard, use the Move to folder action of the actions menu instead.

Renaming folders

1. Click the button of the folder.
2. Click Rename folder.
3. Type the new name in the Folder name field.
4. Click Save.

Note

A folder name must be unique among the folders sharing the same parent.

Deleting folders

1. Click the button of the folder.
2. Click Delete folder.
3. Click Confirm.

Warning

Deleting a folder also deletes everything it contains, including its subfolders and their assets. None of it can be recovered, and the confirmation dialog does not say so.

Folders can also be deleted in bulk, together with assets (see deleting items in bulk).

Usage with the REST API

The Media Library feature has some endpoints that can accessed through Strapi's REST API:

Upload with the REST API

Learn how to use the Strapi's REST API to upload files through your code.

Use public assets in your code

Public assets are static files (e.g., images, video, CSS files, etc.) that you want to make accessible to the outside world.

Because an API may need to serve static assets, every new Strapi project includes by default a folder named /public. Any file located in this directory is accessible if the request's path doesn't match any other defined route and if it matches a public file name (e.g. an image named company-logo.png in /public/ is accessible through /company-logo.png URL).

Tip

index.html files are served if the request corresponds to a folder name (/pictures url will try to serve public/pictures/index.html file).

Caution

The dotfiles are not exposed. It means that every file name that starts with ., such as .htaccess or .gitignore, are not served.