Media Library

Page summary:

Media Library centralizes all uploaded assets with search, filters, and folder organization. This documentation includes provider options, upload workflows, and explanations on inserting media into content.

The Media Library is the Strapi feature that displays all assets uploaded in the Strapi application and allows users to manage them.

IDENTITY CARD

Plan

Free feature

Role & permission

Minimum "Access the Media Library" permission in Roles > Plugins - Upload

Activation

Available and activated by default

Environment

Available in both Development & Production environment

Configuration

Some configuration options for the Media Library are available in the admin panel, and some are handled via your Strapi project's code.

Admin panel configuration

In the admin panel, some Media Library settings are available via the Global Settings to manage the format, file size, and orientation of uploaded assets.

Configuring settings

Path to configure the feature: Settings > Global Settings > Media Library.

1. Define your chosen new Media Library settings:

   Setting name	Instructions	Default value
   Generate AI captions and alt texts automatically on upload!	Enabling this option will turn on AI‑powered metadata generation GrowthThis feature is available with a Growth plan.	Enabled
   Responsive friendly upload	Enabling this option will generate multiple formats (small, medium and large) of the uploaded asset. Default sizes for each format can be configured through the code.	True
   Size optimization	Enabling this option will reduce the image size and slightly reduce its quality.	True
   Auto orientation	Enabling this option will automatically rotate the image according to EXIF orientation tag.	False

2. Click on the Save button.

Tip

When images in your library lack a caption or an alternative text, the AI metadata setting reports how many, and offers a Generate metadata button to generate the missing metadata in the background. Please review the results, AI can make mistakes.

Code-based configuration

The Media Library is powered in the backend server by the Upload package, which can be configured and extended through providers.

Restoring the previous Media Library

5.54.0+

The Media Library described on this page is the default UI since Strapi v5.54.0. To restore the previous interface, set the useLegacyMediaLibrary property to true in the config/features file:

JavaScript

/config/features.js

module.exports = ({ env }) => ({
  useLegacyMediaLibrary: env.bool('USE_LEGACY_MEDIA_LIBRARY', false),
});

TypeScript

/config/features.ts

export default ({ env }) => ({
  useLegacyMediaLibrary: env.bool('USE_LEGACY_MEDIA_LIBRARY', false),
});

Tip

From server code, read this configuration setting with strapi.features.isEnabled('useLegacyMediaLibrary').

Providers

The Media Library supports providers to add upload support from various third parties.

The providers maintained by Strapi are the following. Clicking on a card will redirect you to a docs page with a configuration example:

Amazon S3

Official provider for file uploads to Amazon S3.

Cloudinary

Official provider for media management with Cloudinary.

Local

Default provider for storing files locally on the server.

If you need to install other providers or create your own, please refer to the following guide:

Media Library Providers

Learn how you can add additional providers or create your own.

Info

Code-based configuration instructions on the present page detail options for the default upload provider. If using another provider, please refer to the available configuration parameters in that provider's documentation.

Private storage providers

When the configured provider is private (for example, an S3 bucket with ACL: 'private'), every file URL Strapi returns is a signed URL that expires after signedUrlExpires. Media fields are re-signed on every read, but richtext and blocks fields embed the URL directly in their value.

Strapi stores the unsigned URL for richtext and blocks fields in the database, and signs it again each time the entry is read, in the admin panel and through the REST and Document Service APIs. This also applies to richtext and blocks attributes nested in components and dynamic zones. Rows written before this behavior was introduced, which still hold a signed URL, are rewritten automatically the next time the application starts.

Caution

A file uploaded with a per-file path provider option cannot be re-signed from a richtext or blocks field: the URL is recognized as belonging to the provider, but its storage key cannot be rebuilt from the URL alone, and the signed link returns a 403 error. Media fields have the same limitation.

Available options

When using the default upload provider, the following specific configuration options can be declared in an upload.config object within the config/plugins file. All parameters are optional:

Parameter	Description	Type	Default
providerOptions.localServer	Options that will be passed to koa-static upon which the Upload server is build (see local server configuration)	Object	-
sizeLimit	Maximum file size in bytes (see max file size)	Integer	1000000000 (1 GB in bytes)
breakpoints	Allows you to override the breakpoints sizes at which responsive images are generated when the "Responsive friendly upload" option is set to true (see responsive images)	Object	{ large: 1000, medium: 750, small: 500 }
sharp	Configures sharp image processing options (see sharp configuration)	Object	{ cache: false, concurrency: 1 }
security	Configures validation rules for uploaded files to enhance media security (see security)	Object	-
concurrentUploadRequests	Number of files the admin panel uploads to the server in parallel (see concurrent file uploads). Must be an integer >= 1.	Integer	1
concurrentUploadSize	Number of files the server processes in parallel within a single upload request (see concurrent file uploads). Must be an integer >= 1.	Integer	1

Notes

• The Upload request timeout is defined in the server options, not in the Upload plugin options, as it's not specific to the Upload plugin, but is applied to the whole Strapi server instance (see upload request timeout).
• If you wish to override the image function to generate custom file names, please refer to the Plugins extension documentation.

Example custom configuration

The following is an example of a custom configuration for the Upload plugin when using the default upload provider:

JavaScript

/config/plugins.js

module.exports = ({ env })=>({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
      sizeLimit: 250 * 1024 * 1024, // 256mb in bytes
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
      sharp: {
        cache: true,
        concurrency: 4,
      },
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
      concurrentUploadSize: 5,
    },
  },
});

TypeScript

/config/plugins.ts

export default () => ({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
      sizeLimit: 250 * 1024 * 1024, // 256mb in bytes
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
      sharp: {
        cache: true,
        concurrency: 4,
      },
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
      concurrentUploadSize: 5,
    },
  },
})

Local server

By default Strapi accepts localServer configurations for locally uploaded files. These will be passed as the options for koa-static.

You can provide them by creating or editing the /config/plugins file. The following example sets the max-age header:

JavaScript

/config/plugins.js

module.exports = ({ env })=>({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
    },
  },
});

TypeScript

/config/plugins.ts

export default ({ env }) => ({
  upload: {
    config: {
      providerOptions: {
        localServer: {
          maxage: 300000
        },
      },
    },
  },
});

Max file size

Strapi Cloud

On Strapi Cloud, upload size limits are enforced at the infrastructure level. They cannot be raised via the strapi::body middleware config. See Upload size limits for Strapi Cloud for per-plan values and the memory-based recommendation for image uploads.

The Strapi middleware in charge of parsing requests needs to be configured to support file sizes larger than the default of 1 GB. This must be done in addition to provider options passed to the Upload package for sizeLimit.

Caution

You may also need to adjust any upstream proxies, load balancers, or firewalls to allow for larger file sizes. For instance, Nginx has a configuration setting called client_max_body_size that must be adjusted, since its default is only 1mb.

The middleware used by the Upload package is the body middleware. You can pass configuration to the middleware directly by setting it in the /config/middlewares file:

JavaScript

/config/middlewares.js

module.exports = [
  // ...
  {
    name: "strapi::body",
    config: {
      formLimit: "256mb", // modify form body
      jsonLimit: "256mb", // modify JSON body
      textLimit: "256mb", // modify text body
      formidable: {
        maxFileSize: 250 * 1024 * 1024, // multipart data, modify here limit of uploaded file size
      },
    },
  },
  // ...
];

TypeScript

/config/middlewares.ts

export default [
  // ...
  {
    name: "strapi::body",
    config: {
      formLimit: "256mb", // modify form body
      jsonLimit: "256mb", // modify JSON body
      textLimit: "256mb", // modify text body
      formidable: {
        maxFileSize: 250 * 1024 * 1024, // multipart data, modify here limit of uploaded file size
      },
    },
  },
  // ...
];

In addition to the middleware configuration, you can pass the sizeLimit, which is an integer in bytes, in the /config/plugins file:

JavaScript

/config/plugins.js

module.exports = {
  // ...
  upload: {
    config: {
      sizeLimit: 250 * 1024 * 1024 // 256mb in bytes
    }
  }
};

TypeScript

/config/plugins.ts

export default {
  // ...
  upload: {
    config: {
      sizeLimit: 250 * 1024 * 1024 // 256mb in bytes
    }
  }
};

Security

The Upload plugin validates files based on their actual MIME type rather than the declared file extension. Only files matching the defined security rules are uploaded.

The security configuration provides 2 options: allowedTypes or deniedTypes, which let you control which file types can or cannot be uploaded.

Apps scaffolded with create-strapi-app include a pre-configured security block in the generated config/plugins.* file. See the Security defaults generated by create-strapi-app details block below for the full lists.

Security defaults generated by create-strapi-app:

New projects declare the 2 lists as separate variables and pass them to the upload plugin, alongside the other generated plugin configuration:

JavaScript

/config/plugins.js

const allowedMediaTypes = [
  'image/*',
  'video/*',
  'audio/*',
  'application/pdf',
  'application/msword',
  'application/vnd.openxmlformats-officedocument.*',
  'text/plain',
  'text/csv',
];

const deniedTypes = [
  'image/svg+xml',
  'application/vnd.microsoft.portable-executable',
  'application/x-msdownload',
  'application/x-msdos-program',
  'application/x-executable',
  'application/x-dosexec',
  'application/x-sh',
  'text/x-shellscript',
  'application/x-mach-binary',
];

module.exports = ({ env }) => ({
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: allowedMediaTypes,
        deniedTypes,
      },
    },
  },
});

TypeScript

/config/plugins.ts

import type { Core } from '@strapi/strapi';

const allowedMediaTypes = [
  'image/*',
  'video/*',
  'audio/*',
  'application/pdf',
  'application/msword',
  'application/vnd.openxmlformats-officedocument.*',
  'text/plain',
  'text/csv',
];

const deniedTypes = [
  'image/svg+xml',
  'application/vnd.microsoft.portable-executable',
  'application/x-msdownload',
  'application/x-msdos-program',
  'application/x-executable',
  'application/x-dosexec',
  'application/x-sh',
  'text/x-shellscript',
  'application/x-mach-binary',
];

const config = ({ env }: Core.Config.Shared.ConfigParams): Core.Config.Plugin => ({
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: allowedMediaTypes,
        deniedTypes,
      },
    },
  },
});

export default config;

SVG uploads

Since Strapi 5.52.2+, image/svg+xml is part of the deniedTypes generated by create-strapi-app, so SVG uploads are refused even though they match the image/* wildcard in allowedTypes. An explicit deniedTypes entry always takes precedence over a wildcard in allowedTypes.

SVG files can embed browser-active content such as scripts and event handlers, which is why they are denied by default. This affects newly generated projects only. Existing projects keep their current configuration unless you add the same entry yourself.

To accept SVG uploads, remove image/svg+xml from deniedTypes in your config/plugins.* file (see security). Serve the resulting files from a domain that does not share cookies or local storage with your application, or with a Content-Disposition: attachment header, so an uploaded SVG cannot run scripts in the context of your site.

Note

You can use allowedTypes and deniedTypes separately or together to fine-tune which files are accepted. Files must match an allowed type and must not match any denied type. If you use a wildcard like * in allowedTypes, you can narrow down the validation by specifying exceptions in deniedTypes.

File type detection for ambiguous MIME types

When browsers report generic MIME types for files (such as application/octet-stream), Strapi's Media Library performs file-type detection by examining the file's actual content bytes. This ensures accurate file classification and filtering, particularly for formats like .mov files on Windows systems, which are often reported with generic MIME types by the browser.

The file type detection is used for:

• Classifying media in the Media Library preview and grid
• Validating media field constraints (e.g., allowedTypes: ['video/*']) in the Content Manager

Note

The server remains the security boundary. While the admin panel performs client-side file type detection for better UX, the backend validates the file's MIME type before storage. This means that even if the browser initially misidentifies a file type, the correct MIME type is detected and stored on the server.

You can provide them by creating or editing the /config/plugins file. The following is an example of how to combine allowedTypes and deniedTypes:

JavaScript

/config/plugins.js

module.exports = {
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
    }
  }
};

TypeScript

/config/plugins.ts

export default {
  // ...
  upload: {
    config: {
      security: {
        allowedTypes: ['image/*', 'application/*'],
        deniedTypes: ['application/x-sh', 'application/x-dosexec']
      },
    }
  }
};

Upload request timeout

By default, the value of strapi.server.httpServer.requestTimeout is set to 330 seconds. This includes uploads.

To make it possible for users with slow internet connection to upload large files, it might be required to increase this timeout limit. The recommended way to do it is by setting the http.serverOptions.requestTimeout parameter in the config/servers file.

An alternate method is to set the requestTimeout value in the bootstrap function that runs before Strapi gets started. This is useful in cases where it needs to change programmatically, for example to temporarily disable and re-enable it:

JavaScript

/index.js

module.exports = {

  //...

  bootstrap({ strapi }) {
    // Set the requestTimeout to 1,800,000 milliseconds (30 minutes):
    strapi.server.httpServer.requestTimeout = 30 * 60 * 1000;
  },
};

TypeScript

/index.ts

export default {

  //...

  bootstrap({ strapi }) {
    // Set the requestTimeout to 1,800,000 milliseconds (30 minutes):
    strapi.server.httpServer.requestTimeout = 30 * 60 * 1000;
  },
};

Concurrent file uploads

Bulk uploads are controlled by 2 options that set how many files Strapi handles at the same time:

Parameter	Description	Type	Default
concurrentUploadRequests	Number of files the admin panel uploads to the server in parallel.	Integer	1
concurrentUploadSize	Number of files the server processes in parallel within a single upload request.	Integer	1

Both default to 1, so files are uploaded and processed one at a time. Raising concurrentUploadRequests makes the admin panel send more upload requests at the same time, and raising concurrentUploadSize makes the server process more files at once within a single request. Both speed up bulk uploads at the cost of higher load on the server.

JavaScript

/config/plugins.js

module.exports = () => ({
  upload: {
    config: {
      concurrentUploadRequests: 4,
      concurrentUploadSize: 2,
    },
  },
});

TypeScript

/config/plugins.ts

export default () => ({
  upload: {
    config: {
      concurrentUploadRequests: 4,
      concurrentUploadSize: 2,
    },
  },
});

Warning

Both values must be integers greater than or equal to 1. Any other value, 0 included, prevents Strapi from starting.

Note

concurrentUploadRequests is only read by the Media Library. concurrentUploadSize applies to every upload, because the server enforces it.

Responsive Images

When the Responsive friendly upload admin panel setting is enabled, the plugin will generate the following responsive image sizes:

Name	Largest dimension
large	1000px
medium	750px
small	500px

These sizes can be overridden in /config/plugins:

JavaScript

/config/plugins.js

module.exports = ({ env }) => ({
  upload: {
    config: {
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
    },
  },
});

TypeScript

/config/plugins.ts

export default ({ env }) => ({
  upload: {
    config: {
      breakpoints: {
        xlarge: 1920,
        large: 1000,
        medium: 750,
        small: 500,
        xsmall: 64
      },
    },
  },
});

Caution

Breakpoint changes will only apply to new images, existing images will not be resized or have new sizes generated.

Sharp configuration

The sharp option configures the sharp image processing library used for generating responsive image formats. Adjusting these settings can help reduce memory usage during image processing, which is particularly useful for memory-constrained environments.

Parameter	Description	Type	Default
cache	Enables or disables libvips' operation cache. Disabling the cache reduces memory usage.	Boolean	false
concurrency	Sets the number of threads libvips uses for image processing. Lower values reduce peak memory usage but may slow down processing.	Integer	1

The default values (cache: false, concurrency: 1) are optimized for low memory usage. For environments with more available memory, you can enable caching and increase concurrency to improve image processing performance:

JavaScript

/config/plugins.js

module.exports = ({ env }) => ({
  upload: {
    config: {
      sharp: {
        cache: true,
        concurrency: 4,
      },
    },
  },
});

TypeScript

/config/plugins.ts

export default ({ env }) => ({
  upload: {
    config: {
      sharp: {
        cache: true,
        concurrency: 4,
      },
    },
  },
});

Usage

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.

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:

Strapi v5.54.0 introduces a revamped Media Library. The following table highlights the main changes in the UI:

In the previous UI	In the new Media Library 5.54.0+This feature requires Strapi version 5.54.0+ or later.
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
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, the menu 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

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.

Supported files

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).

File previews

Zip, xls, csv, and json files are not previewed. Images, video, and audio files are previewed.

There are 3 ways to add assets: by uploading from your computer, by dragging and dropping into the Media Library UI, or from a URL.

Uploading files from your computer with the New button

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 from your computer 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 upload dialog reports byte-level progress as the server fetches each file: the progress bar advances in real time during the fetch phase, then hands off to the upload step and completes. 5.53.1+

Note

When the remote server does not include a Content-Length response header, the total size is unknown. The progress bar stays indeterminate for that file until the fetch completes, then completes normally.

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, press the Esc key while still in 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, or a custom range	For presets: is exactly, within the last, not within the last For custom date ranges: 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 button to lock aspect ratio, so it resizes 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.

Info

• 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.
• 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 Copy link to media and Download 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 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

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 MCP server

AI clients connected to the Strapi MCP server can browse and manage the Media Library through dedicated tools: 3 read-only tools that list assets, return a single asset and return the folder tree, and 7 write tools that update asset metadata, move and delete assets, and create, rename, move and delete folders (see Media Library tools).

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.