diff --git a/docusaurus/docs/cms/configurations/features.md b/docusaurus/docs/cms/configurations/features.md index 01fb68719b..f87fde5ba3 100644 --- a/docusaurus/docs/cms/configurations/features.md +++ b/docusaurus/docs/cms/configurations/features.md @@ -111,6 +111,5 @@ Developers can use the following APIs to interact with future flags: | Property name | Related feature | Suggested environment variable name | Maturity | | ------------- | --------------- | ---------------------------------- | -------- | -| `betaMediaLibrary` | [Media Library](/cms/features/media-library) | `STRAPI_FUTURE_BETA_MEDIA_LIBRARY` | The feature works end to end, and its property name, route and menu entry are already the ones it will ship with. It may still change before it becomes generally available. | | `experimental_firstPublishedAt` | [Draft & Publish](/cms/features/draft-and-publish#recording-the-first-publication-date) | `STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT` | The feature works, but its design is still being validated against real usage. | diff --git a/docusaurus/docs/cms/features/media-library-beta.md b/docusaurus/docs/cms/features/media-library-beta.md deleted file mode 100644 index 21728d924c..0000000000 --- a/docusaurus/docs/cms/features/media-library-beta.md +++ /dev/null @@ -1,597 +0,0 @@ ---- -title: Media Library beta -displayed_sidebar: cmsSidebar -description: Use the reworked Media Library available behind the betaMediaLibrary future flag. -unlisted: true -toc_max_heading_level: 5 -tags: -- admin panel -- features -- media library ---- - -import ScreenshotNumberReference from '/src/components/ScreenshotNumberReference.jsx'; -import StrapiAiCredits from '/docs/snippets/strapi-ai-credits.md' - -# Media Library beta - -Strapi has completely reworked the Media Library UI. This page describes the reworked UI, which is available as a beta feature behind the `betaMediaLibrary` future flag, before it becomes the default UI. - -Read the [Media Library](/cms/features/media-library) page for how to enable the flag, and for every configuration option, which the flag does not change. - -## Usage {#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](/cms/features/content-manager#creating--writing-content). - -:::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](/cms/features/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 on the left lists _Home_ and the full folder hierarchy (see [navigating folders](#navigating-folders)). -- The page title 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 creates a folder or uploads assets (see [adding assets](#adding-assets) and [adding folders](#adding-folders)). -- The toolbar spans the row above the list. Use it to filter, search and sort the list (see [finding assets](#finding-assets)), and to switch between the grid view and the table view (see [switching views](#switching-views)). -- The list 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](#selecting-items)) and a button (see [using the item actions menu](#item-actions)). 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](#adding-assets)) | -| Breadcrumbs above the list | A folder tree on the left (see [navigating folders](#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](/cms/features/media-library#configuring-the-view)) | -| A button opening a search field | A search field always displayed in the toolbar (see [searching assets](#searching-assets)) | -| A _Details_ window that covers the library | A details panel that leaves the list usable (see [managing individual assets](#managing-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](#cropping-images)) | - -
- -:::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](#sorting-assets)). -::: - -#### Navigating folders {#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 {#item-actions} - -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-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](/cms/features/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](/cms/features/media-library#security)) and by the maximum file size (see [max file size](/cms/features/media-library#max-file-size)). SVG files are denied by default in projects generated with Strapi and later (see [SVG uploads](/cms/features/media-library#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](#moving-assets)). - -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](#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](#moving-assets)). -::: - -#### 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 {#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`](/cms/features/media-library#concurrent-file-uploads) to upload several files in parallel. - -#### Automatically generating metadata with Strapi AI {#ai-powered-metadata-generation} - - -[When enabled](/cms/configurations/admin-panel#strapi-ai), 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](/cms/features/media-library#configuring-settings) if needed. - -Metadata can also be generated for images that already exist in the library, either from the [Media Library settings](/cms/features/media-library#configuring-settings) for every image that lacks one, or with the **Create metadata** bulk action for a specific selection (see [generating metadata in bulk](#bulk-metadata)). - - - -:::note Strapi AI credits - -::: - -### 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](#searching-assets) 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 {#managing-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](#cropping-images)). -- 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 {#editing-assets} - -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](#moving-assets) for the other options. -::: - -#### Cropping images and setting a focus area {#cropping-images} - -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](#ai-powered-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](#bulk-delete)). - -### 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 {#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 {#bulk-move} - -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](#moving-assets)). - -#### Deleting items in bulk {#bulk-delete} - -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 {#bulk-metadata} - - -When [Strapi AI](/cms/configurations/admin-panel#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](#navigating-folders). - -:::note -Folders follow the permission system of assets (see [Users & Permissions feature](/cms/features/users-permissions)). 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 {#moving-assets} - -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](#bulk-move)). 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](#managing-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](#bulk-delete)). - -### Usage with the REST API - -The Media Library feature has some endpoints that can accessed through Strapi's REST API: - - - - - -### Use public assets in your code {#public-assets} - -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. -::: diff --git a/docusaurus/docs/cms/features/media-library.md b/docusaurus/docs/cms/features/media-library.md index 0771cb1e85..10525fc2c6 100644 --- a/docusaurus/docs/cms/features/media-library.md +++ b/docusaurus/docs/cms/features/media-library.md @@ -31,52 +31,6 @@ The Media Library is the Strapi feature that displays all -:::strapi New Media Library available in -Strapi has completely reworked the Media Library UI. It is available as a beta feature for the next few weeks, before it becomes the default UI. Enable it by setting the `future.betaMediaLibrary` property to `true` in the `config/features` file: - - - - - -```js title="/config/features.js" -module.exports = () => ({ - future: { - // highlight-next-line - betaMediaLibrary: true, - }, -}); -``` - - - - -```ts title="/config/features.ts" -export default () => ({ - future: { - // highlight-next-line - betaMediaLibrary: true, - }, -}); -``` - - - - -Restart your Strapi application after the configuration change. Set the property to `false` and restart Strapi to go back to the previous UI: no asset, folder or setting is lost when you switch either way. - -The [Usage](#usage) section of this page describes the UI that is enabled by default, and the guided tour above shows it too. While new UI is in beta, it is documented on its own page, [Media Library beta](/cms/features/media-library-beta). The [Configuration](#configuration) section applies to both. - -The flag changes the Media Library page of the admin panel, and adds the upload dialog described in [following upload progress](/cms/features/media-library-beta#upload-progress) to the whole admin panel. The following are not affected and still behave as documented: - -- the media field of the Content Manager, which still opens the previous asset picker, -- the _Settings > Global Settings > Media Library_ page, -- the [Upload REST API](/cms/api/rest/upload). - -The Media Library page displays a notice reminding you that this is a beta and that some features are still in progress. Read the [features configuration](/cms/configurations/features) documentation before enabling the flag, where the `STRAPI_FUTURE_BETA_MEDIA_LIBRARY` environment variable is also documented. - -You can and report any issue you run into on the . -::: - ## Configuration Some configuration options for the Media Library are available in the admin panel, and some are handled via your Strapi project's code. @@ -116,15 +70,15 @@ When images in your library lack a caption or an alternative text, the AI metada **Path to configure the feature:** Media Library -:::caution With the beta Media Library enabled -The button and the view configuration page described below are not available while the `betaMediaLibrary` future flag is enabled, because the beta Media Library replaces both settings: +:::caution +The button and the view configuration page described below are not available in the Media Library, which replaces both settings: - assets load as you scroll instead of being paginated, so there is no page size to define, -- the sort order is chosen from the toolbar and stored in the page URL (see [sorting assets](/cms/features/media-library-beta#sorting-assets)). +- the sort order is chosen from the toolbar and stored in the page URL (see [sorting assets](#sorting-assets)). -A bookmarked link to `/admin/plugins/upload/configuration` displays a blank page rather than an error while the flag is enabled. +A bookmarked link to `/admin/plugins/upload/configuration` displays a blank page rather than an error. -Both settings still apply to the media field of the Content Manager. To change them, set the flag back to `false` temporarily. +Both settings still apply to the media field of the Content Manager. To change them, set the `useLegacyMediaLibrary` property to `true` temporarily. ::: 1. Click on the button just above the list of folders and assets, on the right side of the interface. @@ -135,7 +89,7 @@ Both settings still apply to the media field of the Cont | Default sort order | Use the dropdown to define the default order in which assets are displayed. This can be overriden when sorting assets in the Media Library. | :::note -With the beta Media Library disabled, both settings are used as the defaults in the Media Library and in the Content Manager's media upload modal. These settings are global across the entire Strapi project for all users. +Both settings are used as the defaults in the Content Manager's media upload modal. These settings are global across the entire Strapi project for all users. ::: ({ -## Usage +## Usage {#usage} **Path to use the feature:** Media Library -:::info -Strapi supports uploading images from the admin panel or programmatically. From the API, you can send a multipart/form-data request to `/api/upload` with the image file and optional `fileInfo` metadata for captions and alt text (see [REST API documentation](/cms/api/rest/upload#upload-files) for more information). -::: - 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](/cms/features/content-manager#creating--writing-content). +:::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](/cms/features/users-permissions) to grant the _Create_, _Update_, _Download_ and _Copy link_ permissions of the Upload plugin. +::: + +### Interface overview + -From the Media Library, it is possible to: +The Media Library is organized in the following areas: -- upload a new asset (see [adding assets](/cms/features/media-library#adding-assets)) or create a new folder (see [organizing assets with folders](/cms/features/media-library#organizing-assets-with-folders)) , -- sort the assets and folders or set filters to find assets and folders more easily, -- toggle between the list view and the grid view to display assets, access settings to [configure the view](#configuring-the-view), and make a textual search to find a specific asset or folder, -- and view, navigate through, and manage folders . +- The folder tree on the left lists _Home_ and the full folder hierarchy (see [navigating folders](#navigating-folders)). +- The page title 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 creates a folder or uploads assets (see [adding assets](#adding-assets) and [adding folders](#adding-folders)). +- The toolbar spans the row above the list. Use it to filter, search and sort the list (see [finding assets](#finding-assets)), and to switch between the grid view and the table view (see [switching views](#switching-views)). +- The list displays the folders and assets of the current location. More assets load as you scroll. -:::tip -Click the search icon on the right side of the user interface to use a text search and find one of your assets or folders more quickly! +Each folder and asset in the list has a checkbox to select it (see [selecting items](#selecting-items)) and a button (see [using the item actions menu](#item-actions)). 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 new Media Library | +| --- | --- | +| **Add new assets** and **Add new folder** buttons | A single **New** button that does both (see [adding assets](#adding-assets)) | +| Breadcrumbs above the list | A folder tree on the left (see [navigating folders](#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](#configuring-the-view)) | +| A button opening a search field | A search field always displayed in the toolbar (see [searching assets](#searching-assets)) | +| A _Details_ window that covers the library | A details panel that leaves the list usable (see [managing individual assets](#managing-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](#cropping-images)) | + +
+ +:::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. ::: - - +- 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 {#item-actions} + +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-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](/cms/features/users-permissions). +::: ### Adding assets
-List of media types and extensions supported by the Media Library +Media types the Media Library previews -| Media type | Supported extensions | +| Media type | Extensions | | ---------- | --------------------------------------------------------------- | | Image | - JPEG
- PNG
- GIF
- SVG
- TIFF
- ICO
- DVU | | Video | - MPEG
- MP4
- MOV (Quicktime)
- WMV
- AVI
- FLV | @@ -874,45 +888,94 @@ Just above the list of folders and assets and next to the ! and later, even though they match the supported image types (see [SVG uploads](#svg-uploads)). +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](#security)) and by the maximum file size (see [max file size](#max-file-size)). SVG files are denied by default in projects generated with Strapi and later (see [SVG uploads](#svg-uploads)).
-1. Click the **Add new assets** button in the upper right corner of the Media Library. -2. Choose whether you want to upload the new asset from your computer or from an URL: - - from the computer, either drag & drop the asset directly or browse files on your system, - - from an URL, type or copy and paste an URL(s) in the _URL_ field, making sure multiple URLs are separated by carriage returns, then click **Next**. -3. (optional) Click the edit button to view asset metadata and define a _File name_, _Alternative text_ and a _Caption_ for the asset (see [Managing individual assets](#managing-assets)). -4. (optional) Add more assets by clicking **Add new assets** and going back to step 2. -5. Click on **Upload assets to the library**. +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](#moving-assets)). + +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 -#### Automatically generating metadata with Strapi AI {#ai-powered-metadata-generation} - +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](#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](#moving-assets)). +::: -[When enabled](/cms/configurations/admin-panel#strapi-ai), Strapi AI automatically generates alternative text and captions for images uploaded to the Media Library, helping you improve content accessibility and SEO. A modal window displays the AI-generated alternative text and caption, allowing you to review the metadata and modify it if needed: +#### 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 {#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. -AI metadata generation only works with images, not files or videos. The feature is enabled by default, but can be disabled in the [Media Library settings](#configuring-settings) if needed. +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`](#concurrent-file-uploads) to upload several files in parallel. + +#### Automatically generating metadata with Strapi AI {#ai-powered-metadata-generation} + + +[When enabled](/cms/configurations/admin-panel#strapi-ai), 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](#configuring-settings) if needed. -The [Media Library settings](#configuring-settings) also allow generating metadata for existing images that lack alternative text or captions. This feature is currently in . +Metadata can also be generated for images that already exist in the library, either from the [Media Library settings](#configuring-settings) for every image that lacks one, or with the **Create metadata** bulk action for a specific selection (see [generating metadata in bulk](#bulk-metadata)). ::: -### Managing individual assets {#managing-assets} +### 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. -The Media Library allows managing assets, which includes modifying assets' file details and location, downloading and copying the link of the assets file, and deleting assets. Image files can also be cropped. +To leave the search, click the **Clear** button inside the search field, or navigate to a folder in the folder tree. -#### Editing assets +When a search returns nothing, the list is replaced by a _No results found_ message with a **Clear search** button. -Click on the edit button of an asset to open up the "Details" window, where all the available asset management options are available. +#### 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 | -- On the left, above the preview of the asset, control buttons allow performing various actions: - - click on the delete button to delete the asset, - - click on the download button to download the asset, - - click on the copy link button to copy the asset's link to the clipboard, - - optionally, click on the crop button to enter cropping mode for the image (see [Cropping images](#cropping-images)). - - optionally, click on the pin button to enter focal point mode for the image (see [Adding a focal point](#adding-a-focal-point)). -- On the right, meta data for the asset is displayed at the top of the window and the fields below can be used to update the _File name_, _Alternative text_, _Caption_ and _Location_ (see [Organizing assets with folders](#organizing-assets-with-folders)) for the asset . -- At the bottom, the **Replace Media** button can be used to replace the asset file but keep the existing content of the other editable fields, and the **Finish** button is used to confirm any updates to the fields. +To filter the list: -#### Moving assets +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. -1. Click on the edit button for the asset to be moved. -2. In the window that pops up, click the _Location_ field and choose a different folder from the drop-down list. -3. Click **Save** to confirm. +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 -Assets can also be moved to other folders from the main view of the Media Library (see [Organizing assets with folders](#organizing-assets-with-folders)). This includes the ability to move several assets simultaneously. +Filters apply to the location you are browsing, not to the whole library. Use the [search](#searching-assets) 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. ::: -#### Cropping images +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. -1. Click on the edit button for the asset to be cropped. -2. In the window that pops up, click the crop button to enter cropping mode. -3. Crop the image using handles in the corners to resize the frame. The frame can also be moved by drag & drop. -4. Click the crop button to validate the new dimensions, and choose either to **crop the original asset** or to **duplicate & crop the asset** (i.e. to create a copy with the new dimensions while keeping the original asset untouched). Alternatively, click the stop cropping button to cancel and quit cropping mode. - -5. Click **Finish** to save changes to the file. +#### Sorting assets -#### Adding a focal point +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_. -A focal point ensures the most important part of an image remains visible when the image is cropped or resized in different contexts. + -To add a focal point to an image: +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. -1. Click on the edit button. -2. In the window that pops up, click on the pin button to enter focal point mode. -3. Move the crosshair to the desired location and click to set the focal point. -4. Click the check button to validate the new focal point. Alternatively, click the cancel button to abandon changes and exit focal point mode. -5. Click the reset button to reset the focal point to the center of the image. -6. Click **Finish** to save changes to the file. +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. -#### Deleting assets +:::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. +::: -1. Click on the edit button for the asset to be deleted. -2. In the window that pops up, click the delete button in the control buttons bar above the asset's preview. -3. Click **Confirm**. +### Managing individual assets {#managing-assets} -:::tip -Assets can also be deleted individually or in bulk from the main view of the Media Library. Select assets by clicking on their checkbox in the top left corner, then click the Delete icon at the top of the window, below the filters and sorting options. -::: +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. -### Organizing assets with folders + + +The panel is organized as follows: -Folders in the Media Library help you organize uploaded assets. Folders sit at the top of the Media Library view or are accessible from the Media field popup when using the [Content Manager](/cms/features/content-manager). +- 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](#cropping-images)). +- 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. -From the Media Library, it is possible to view the list of folders and browse a folder's content, create new folders, edit an existing folder, move assets to a folder, and delete a folder. +#### Editing an asset name, caption and alternative text {#editing-assets} + +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 -Folders follow the permission system of assets (see [Users & Permissions feature](/cms/features/users-permissions)). It is not yet possible to define specific permissions for a folder. +**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. ::: -By default, the Media Library displays folders and assets created at the root level. Clicking a folder navigates to this folder, and displays the following elements: +:::tip +The _Location_ field of the same panel moves a single asset to another folder. See [moving assets and folders](#moving-assets) for the other options. +::: + +#### Cropping images and setting a focus area {#cropping-images} -- the folder title and breadcrumbs to navigate to a parent folder -- the subfolders the current folder contains -- all assets from this folder +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. -From this dedicated folder view, folders and assets can be managed, filtered, sorted and searched just like from the main Media Library. +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 navigate back to the parent folder, one level up, use the **Back** button at the top of the interface. +To leave the editor without changing anything, click **Cancel**. -:::tip -The breadcrumb navigation can also be used to go back to a parent folder: click on a folder name to directly jump to it or click on the 3 dots `/img.` and select a parent folder from the drop-down list. +:::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. ::: -#### Adding folders +:::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](#ai-powered-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. +::: -1. Click on **Add new folder** in the upper right of the Media Library interface. -2. In the window that pops up, type a name for the new folder in the _Name_ field. -3. (optional) In the _Location_ drop-down list, choose a location for the new folder. The default location is the active folder. -4. Click **Create**. +#### 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 -There is no limit to how deep your folders hierarchy can go, but bear in mind it might take some effort to reach a deeply nested subfolder, as the Media Library currently has no visual hierarchy indication. Searching for files using the on the right side of the user interface might be a faster alternative to finding the asset you are looking for. +**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. ::: -#### Moving assets to a folder +#### Deleting assets -Assets and folders can be moved to another folder from the root view of the Media Library or from any view for a dedicated folder. +1. Click the asset in the list to open its details panel. +2. Click the **Delete this file** button. +3. Click **Confirm**. -1. Select assets and folder to be moved, by clicking the checkbox on the left of the folder name or clicking the asset itself. -2. Click the **Move** button at the top of the interface. -3. In the _Move elements to_ pop-up window, select the new folder from the _Location_ drop-down list. -4. Click **Move**. +:::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](#bulk-delete)). + +### 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 {#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. -#### Editing folders +:::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. -Once created, a folder can be renamed, moved or deleted. +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. +::: -1. In the Folders part of the Media library, hover the folder to be edited and click its edit button . -2. In the window that pops up, update the name and location with the _Name_ field and _Location_ drop-down list, respectively. -3. Click **Save**. +#### Moving items in bulk {#bulk-move} -#### Deleting folders +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](#moving-assets)). + +#### Deleting items in bulk {#bulk-delete} + +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 {#bulk-metadata} + + +When [Strapi AI](/cms/configurations/admin-panel#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](#navigating-folders). + +:::note +Folders follow the permission system of assets (see [Users & Permissions feature](/cms/features/users-permissions)). 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. +::: -Deleting a folder can be done either from the list of folders of the Media Library, or when editing a single folder. +:::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 {#moving-assets} + +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](#bulk-move)). 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](#managing-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. +::: -1. Click the checkbox on the left of the folder name. Multiple folders can be selected. -2. Click the **Delete** button above the Folders list. -3. In the _Confirmation_ dialog, click **Confirm**. +#### 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 single folder can also be deleted when editing it: hover the folder, click on its edit icon , and in the window that pops up, click the **Delete folder** button and confirm the deletion. +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](#bulk-delete)). + ### Usage with the REST API The Media Library feature has some endpoints that can accessed through Strapi's REST API: diff --git a/docusaurus/vercel.json b/docusaurus/vercel.json index d9f4ed1966..efc29a6cf2 100644 --- a/docusaurus/vercel.json +++ b/docusaurus/vercel.json @@ -3823,6 +3823,11 @@ "source": "/cms/providers#configuring-providers", "destination": "/cms/features/media-library#providers", "permanent": true + }, + { + "source": "/cms/features/media-library-beta", + "destination": "/cms/features/media-library", + "permanent": true } ] }