From 1d4ce40712e68d92eff850d46bf97d4b4dd107bd Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 18 Jun 2026 02:22:26 +0000 Subject: [PATCH 1/4] Document initiallySelectedAssets prop for Media Library custom components Add new section explaining how to use the MediaLibraryDialog component with the initiallySelectedAssets prop in custom admin components, with a code example. Related to strapi/strapi#26679 --- docusaurus/docs/cms/features/media-library.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docusaurus/docs/cms/features/media-library.md b/docusaurus/docs/cms/features/media-library.md index 990d889f6b..1e51c770dc 100644 --- a/docusaurus/docs/cms/features/media-library.md +++ b/docusaurus/docs/cms/features/media-library.md @@ -550,6 +550,41 @@ export default ({ env }) => ({ +## Using the Media Library component in custom components + +When developing custom admin components or plugins, you can access and use the Media Library dialog component directly. The `MediaLibraryDialog` component supports the `initiallySelectedAssets` prop, which allows you to pre-select assets when the dialog opens. + +### Example: Using MediaLibraryDialog with pre-selected assets + +To use the Media Library component with initially selected assets in a custom component: + +```jsx +import { useStrapiApp } from '@strapi/admin/strapi-admin'; + +export function MyCustomComponent() { + const components = useStrapiApp((state) => state.components); + const MediaLibraryDialog = components['media-library']; + + // Assets to pre-select in the Media Library dialog + const initialAssets = [ + { id: 1, name: 'image1.jpg' }, + { id: 2, name: 'image2.png' }, + ]; + + return ( + { + // Handle selected assets + console.log('Selected assets:', assets); + }} + /> + ); +} +``` + +This feature simplifies the development of custom upload components by ensuring that previously selected items are displayed when users open the Media Library dialog, improving the overall user experience. + ## Usage **Path to use the feature:** Media Library From d668cd928aac011dc4908cae130aa8e567f6673d Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Thu, 18 Jun 2026 14:49:27 +0200 Subject: [PATCH 2/4] Add guide on reusing built-in admin panel components in plugins Moves the MediaLibraryDialog reuse example out of the Media Library feature page into a developer-facing plugins-development guide, using the verified useStrapiApp component-registry API (strapi/strapi#26679). --- .../guides/reuse-admin-panel-components.md | 92 +++++++++++++++++++ docusaurus/sidebars.js | 1 + 2 files changed, 93 insertions(+) create mode 100644 docusaurus/docs/cms/plugins-development/guides/reuse-admin-panel-components.md diff --git a/docusaurus/docs/cms/plugins-development/guides/reuse-admin-panel-components.md b/docusaurus/docs/cms/plugins-development/guides/reuse-admin-panel-components.md new file mode 100644 index 0000000000..0918869a65 --- /dev/null +++ b/docusaurus/docs/cms/plugins-development/guides/reuse-admin-panel-components.md @@ -0,0 +1,92 @@ +--- +title: How to reuse built-in admin panel components in plugins +description: Learn how to access and reuse built-in Strapi admin panel React components, such as the Media Library dialog, in your custom admin components or plugins. +sidebar_label: Reuse admin panel components +displayed_sidebar: cmsSidebar +tags: +- admin panel +- components +- guides +- media library +- plugins +- plugins development +- plugins development guides +--- + +# How to reuse built-in admin panel components in plugins + +When [developing a Strapi plugin](/cms/plugins-development/developing-plugins) or customizing the admin panel, you might want to reuse a React component that Strapi already ships in its admin panel instead of building your own. Built-in components are exposed through the admin panel's component registry, which you access with the `useStrapiApp` hook. + +This guide uses the Media Library dialog (`MediaLibraryDialog`) as an example, but the same approach works for any component registered in the admin panel. + +## Access a component from the registry + +Built-in admin panel components are stored in the `components` object of the Strapi app context. Read it with the `useStrapiApp` hook, passing the name of the consuming component and a selector: + +```jsx +import { useStrapiApp } from '@strapi/admin/strapi-admin'; + +const components = useStrapiApp('MyCustomComponent', (state) => state.components); +const MediaLibraryDialog = components['media-library']; +``` + +The first argument to `useStrapiApp` is a label identifying the consumer (used for error messages); the second is the selector that returns the part of the context you need. + +## Reuse the Media Library dialog + +The `MediaLibraryDialog` component opens the same asset-selection dialog used across the admin panel. It accepts the following props: + +| Prop | Type | Description | +| --- | --- | --- | +| `onSelectAssets` | `(selectedAssets: File[]) => void` | Required. Called with the assets the user selected when they confirm their choice. | +| `onClose` | `() => void` | Required. Called when the dialog is closed. | +| `initiallySelectedAssets` | `File[]` | Optional. Media Library asset objects to pre-select when the dialog opens. | +| `allowedTypes` | `string[]` | Optional. Restricts the asset types that can be selected. Defaults to `['files', 'images', 'videos', 'audios']`. | +| `multiple` | `boolean` | Optional. Allows selecting several assets at once. Defaults to `true`. | + +:::note +`initiallySelectedAssets` expects full Media Library asset objects (the same shape returned by the [Upload API](/cms/api/rest/upload)), not just an `id` and a `name`. +::: + +The following example renders the dialog from a custom component and pre-selects assets when it opens: + +```jsx +import { useState } from 'react'; +import { useStrapiApp } from '@strapi/admin/strapi-admin'; + +export function MyCustomComponent() { + const [isMediaLibraryOpen, setIsMediaLibraryOpen] = useState(false); + const components = useStrapiApp('MyCustomComponent', (state) => state.components); + const MediaLibraryDialog = components['media-library']; + + // Assets to pre-select when the dialog opens. + // Each entry is a full Media Library asset object, not just an id and name. + const initialAssets = [ + { id: 1, name: 'image1.jpg' /* ...other asset fields */ }, + { id: 2, name: 'image2.png' /* ...other asset fields */ }, + ]; + + const handleSelectAssets = (assets) => { + // Handle the assets the user selected + console.log('Selected assets:', assets); + setIsMediaLibraryOpen(false); + }; + + return ( + <> + + {isMediaLibraryOpen && ( + setIsMediaLibraryOpen(false)} + /> + )} + + ); +} +``` + +Pre-selecting assets ensures that previously selected items are displayed when users open the Media Library dialog from your custom component. diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index bc344ead8d..44dfecdc1f 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -589,6 +589,7 @@ const sidebars = { 'cms/plugins-development/guides/admin-permissions-for-plugins', 'cms/plugins-development/guides/store-and-access-data', 'cms/plugins-development/guides/create-components-for-plugins', + 'cms/plugins-development/guides/reuse-admin-panel-components', ], }, 'cms/plugins-development/plugins-extension', From 657201a4c412311590d281132a98b94042c81f45 Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Thu, 18 Jun 2026 14:49:41 +0200 Subject: [PATCH 3/4] Move custom-component dialog usage out of Media Library feature page The developer example now lives in the plugins-development guide. Also adds the required displayed_sidebar frontmatter and fixes a ./public path. --- docusaurus/docs/cms/features/media-library.md | 38 +------------------ 1 file changed, 2 insertions(+), 36 deletions(-) diff --git a/docusaurus/docs/cms/features/media-library.md b/docusaurus/docs/cms/features/media-library.md index 1e51c770dc..646b7a62e2 100644 --- a/docusaurus/docs/cms/features/media-library.md +++ b/docusaurus/docs/cms/features/media-library.md @@ -1,5 +1,6 @@ --- title: Media Library +displayed_sidebar: cmsSidebar sidebar_position: 1 description: Learn to use the Media Library which allows to display and manage all assets uploaded in the application. toc_max_heading_level: 5 @@ -550,41 +551,6 @@ export default ({ env }) => ({ -## Using the Media Library component in custom components - -When developing custom admin components or plugins, you can access and use the Media Library dialog component directly. The `MediaLibraryDialog` component supports the `initiallySelectedAssets` prop, which allows you to pre-select assets when the dialog opens. - -### Example: Using MediaLibraryDialog with pre-selected assets - -To use the Media Library component with initially selected assets in a custom component: - -```jsx -import { useStrapiApp } from '@strapi/admin/strapi-admin'; - -export function MyCustomComponent() { - const components = useStrapiApp((state) => state.components); - const MediaLibraryDialog = components['media-library']; - - // Assets to pre-select in the Media Library dialog - const initialAssets = [ - { id: 1, name: 'image1.jpg' }, - { id: 2, name: 'image2.png' }, - ]; - - return ( - { - // Handle selected assets - console.log('Selected assets:', assets); - }} - /> - ); -} -``` - -This feature simplifies the development of custom upload components by ensuring that previously selected items are displayed when users open the Media Library dialog, improving the overall user experience. - ## Usage **Path to use the feature:** Media Library @@ -875,7 +841,7 @@ The Media Library feature has some endpoints that can accessed through Strapi's 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). +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). From 67c1acdc4c0c9e1064e96b268debae72d2de6746 Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Thu, 18 Jun 2026 14:49:48 +0200 Subject: [PATCH 4/4] Fix sizeLimit default value for the local upload provider The default is 1000000000 (1 GB), as defined in the Upload plugin config, not 1000000 (1 MB). --- .../cms/configurations/media-library-providers/local-upload.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/configurations/media-library-providers/local-upload.md b/docusaurus/docs/cms/configurations/media-library-providers/local-upload.md index 60c4f99cb8..8d1587003a 100644 --- a/docusaurus/docs/cms/configurations/media-library-providers/local-upload.md +++ b/docusaurus/docs/cms/configurations/media-library-providers/local-upload.md @@ -53,7 +53,7 @@ Providers configuration is defined in [the `/config/plugins` file](/cms/configur * `provider` to define the provider name (i.e., `local`) * `providerOptions` to define options that are passed down during the construction of the provider. -For the local Upload provider, `providerOptions` accepts only one parameter: `sizeLimit`, which must be a number. The unit is bytes, and the default value is 1000000. When increasing this limit, also configure the body parser middleware `maxFileSize` so the file can be sent and processed (see [Media Library documentation](/cms/features/media-library#max-file-size) for details). +For the local Upload provider, `providerOptions` accepts only one parameter: `sizeLimit`, which must be a number. The unit is bytes, and the default value is 1000000000 (1 GB). When increasing this limit, also configure the body parser middleware `maxFileSize` so the file can be sent and processed (see [Media Library documentation](/cms/features/media-library#max-file-size) for details). The following is an example configuration: