From 7e0fc296fba491d172805528e2ace3e95874c028 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Fri, 31 Jul 2026 02:26:12 +0000 Subject: [PATCH 1/6] Document optional component screenshot field for Dynamic Zone picker --- .../components-dynamic-zones.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docusaurus/docs/cms/api/entity-service/components-dynamic-zones.md b/docusaurus/docs/cms/api/entity-service/components-dynamic-zones.md index f4bb556a08..75faff916f 100644 --- a/docusaurus/docs/cms/api/entity-service/components-dynamic-zones.md +++ b/docusaurus/docs/cms/api/entity-service/components-dynamic-zones.md @@ -89,3 +89,37 @@ strapi.entityService.update('api::article.article', 1, { }, }); ``` + +## Component screenshots in the Dynamic Zone picker + + + +You can add an optional `screenshot` field to a component's `info` object in its `schema.json` file. When set, the Dynamic Zone component picker in the Content Manager displays a thumbnail preview for that component instead of the default icon. + + + +The `screenshot` field accepts: +- A root-relative path served by Strapi's built-in static middleware (for example, `/_component-screenshots/hero.png`), with the image placed in the project's `public/` directory. +- An absolute URL pointing to a CDN or external image host. + +### Adding a screenshot to a component + +1. Open the component's `schema.json` file and add a `screenshot` field to the `info` object: + + + + ```json + { + "info": { + "displayName": "Hero Section", + "icon": "layout", + "screenshot": "/_component-screenshots/hero-section.png" + } + } + ``` + +2. If using a root-relative path, place the image file in the project's `public` directory at the specified path (for example, `public/_component-screenshots/hero-section.png`). +3. Start or restart Strapi. +4. Open a content type that contains a Dynamic Zone in the Content Manager, then click **Add a component** and expand a component category. + +The picker displays the screenshot as a thumbnail for that component. Hovering over the thumbnail shows an enlarged preview. Components without a `screenshot` continue to display the default icon. From ae4389a491a4d3ac76a051eec018df0b5dcc54df Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:01:03 +0200 Subject: [PATCH 2/6] Document the preview field on the models and Content Manager pages The field is named preview, not screenshot: it was renamed upstream before strapi/strapi#26863 merged. Moved off the Entity Service page, which is deprecated and unlisted, and which the field has nothing to do with. --- .../components-dynamic-zones.md | 34 ------------------- .../docs/cms/backend-customization/models.md | 27 +++++++++++++++ .../docs/cms/features/content-manager.md | 2 ++ 3 files changed, 29 insertions(+), 34 deletions(-) diff --git a/docusaurus/docs/cms/api/entity-service/components-dynamic-zones.md b/docusaurus/docs/cms/api/entity-service/components-dynamic-zones.md index 75faff916f..f4bb556a08 100644 --- a/docusaurus/docs/cms/api/entity-service/components-dynamic-zones.md +++ b/docusaurus/docs/cms/api/entity-service/components-dynamic-zones.md @@ -89,37 +89,3 @@ strapi.entityService.update('api::article.article', 1, { }, }); ``` - -## Component screenshots in the Dynamic Zone picker - - - -You can add an optional `screenshot` field to a component's `info` object in its `schema.json` file. When set, the Dynamic Zone component picker in the Content Manager displays a thumbnail preview for that component instead of the default icon. - - - -The `screenshot` field accepts: -- A root-relative path served by Strapi's built-in static middleware (for example, `/_component-screenshots/hero.png`), with the image placed in the project's `public/` directory. -- An absolute URL pointing to a CDN or external image host. - -### Adding a screenshot to a component - -1. Open the component's `schema.json` file and add a `screenshot` field to the `info` object: - - - - ```json - { - "info": { - "displayName": "Hero Section", - "icon": "layout", - "screenshot": "/_component-screenshots/hero-section.png" - } - } - ``` - -2. If using a root-relative path, place the image file in the project's `public` directory at the specified path (for example, `public/_component-screenshots/hero-section.png`). -3. Start or restart Strapi. -4. Open a content type that contains a Dynamic Zone in the Content Manager, then click **Add a component** and expand a component category. - -The picker displays the screenshot as a thumbnail for that component. Hovering over the thumbnail shows an enlarged preview. Components without a `screenshot` continue to display the default icon. diff --git a/docusaurus/docs/cms/backend-customization/models.md b/docusaurus/docs/cms/backend-customization/models.md index a89ce419ac..b129bbce2c 100644 --- a/docusaurus/docs/cms/backend-customization/models.md +++ b/docusaurus/docs/cms/backend-customization/models.md @@ -96,6 +96,8 @@ The `info` key in the model's schema describes information used to display the m | `singularName` | String | Singular form of the content-type name.
Used to generate the API routes and databases/tables collection.

Should be kebab-case. | | `pluralName` | String | Plural form of the content-type name.
Used to generate the API routes and databases/tables collection.

Should be kebab-case. | | `description` | String | Description of the model | +| `icon` | String | Name of the [Strapi icon](https://github.com/strapi/design-system) used to represent the model in the admin panel | +| `preview` | String | Path or URL of an image used to represent a component in the admin panel.

Components only. See [Component preview images](#component-preview-images). | ```json title="./src/api/[api-name]/content-types/restaurant/schema.json" @@ -107,6 +109,31 @@ The `info` key in the model's schema describes information used to display the m }, ``` +#### Component preview images + +Components accept an optional `preview` parameter in their `info` object. It points to an image representing the component in the [dynamic zone picker](/cms/features/content-manager#dynamic-zones). + +The `preview` parameter accepts: + +- A root-relative path to an image placed in the project's `public` directory, for instance `/_component-screenshots/hero-section.png`. The image is then served by the [`public` middleware](/cms/configurations/middlewares#public), which does not serve paths starting with `/uploads/`. +- An absolute URL pointing to an external image host. + +```json title="./src/components/sections/hero-section.json" +{ + "info": { + "displayName": "Hero Section", + "icon": "layout", + "preview": "/_component-screenshots/hero-section.png" + } +} +``` + +When `preview` is omitted, or when the image fails to load, the admin panel falls back to the component's `icon`. + +:::note +The `preview` parameter must be set manually in the component's schema file. The Content-type Builder cannot upload a preview image yet. +::: + ### Model attributes The content structure of a model consists of a list of attributes. Each attribute has a `type` parameter, which describes its nature and defines the attribute as a simple piece of data or a more complex structure used by Strapi. diff --git a/docusaurus/docs/cms/features/content-manager.md b/docusaurus/docs/cms/features/content-manager.md index 2692df834f..83652048d9 100644 --- a/docusaurus/docs/cms/features/content-manager.md +++ b/docusaurus/docs/cms/features/content-manager.md @@ -430,6 +430,8 @@ Dynamic zones are a combination of components, which themselves are composed of 2. Choose a component available for the dynamic zone. 3. Fill in the fields of the component. +Components display an icon in the picker. A component that defines a [preview image](/cms/backend-customization/models#component-preview-images) displays it as a thumbnail instead. Hovering over the thumbnail shows an enlarged preview. + Dynamic zones' components can also be reordered or deleted directly in the edit view, using buttons displayed in the top right corner of the component area. - Use the drag & drop button to reorder components in your dynamic zone. From cb39b205751a962484e5f43fe4083a752d982c3b Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Thu, 27 Aug 2026 11:00:32 +0200 Subject: [PATCH 3/6] Clarify the component picker preview image wording in the Content Manager The sentence described what readers see during step 2 but sat after the numbered steps, and its bare use of "preview" was ambiguous with the Preview feature. --- docusaurus/docs/cms/features/content-manager.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docusaurus/docs/cms/features/content-manager.md b/docusaurus/docs/cms/features/content-manager.md index 83652048d9..0d1f5d15ea 100644 --- a/docusaurus/docs/cms/features/content-manager.md +++ b/docusaurus/docs/cms/features/content-manager.md @@ -426,12 +426,14 @@ Dynamic zones are a combination of components, which themselves are composed of }} /> +In the component picker, each component displays an icon. +A component whose schema defines a preview image displays that image as a thumbnail instead, and hovering over it shows an enlarged version. +Developers set this image in the [component schema](/cms/backend-customization/models#component-preview-images). + 1. Click on the **Add a component to [dynamic zone name]** button. 2. Choose a component available for the dynamic zone. 3. Fill in the fields of the component. -Components display an icon in the picker. A component that defines a [preview image](/cms/backend-customization/models#component-preview-images) displays it as a thumbnail instead. Hovering over the thumbnail shows an enlarged preview. - Dynamic zones' components can also be reordered or deleted directly in the edit view, using buttons displayed in the top right corner of the component area. - Use the drag & drop button to reorder components in your dynamic zone. From 444ad8d01358e9743a06b0719a1c73b49b8f798e Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Thu, 27 Aug 2026 11:01:00 +0200 Subject: [PATCH 4/6] Distinguish the component preview parameter from the Preview feature The docs already use "preview" for the front-end Preview feature and its config/admin preview object, so the component info parameter needed disambiguating. --- docusaurus/docs/cms/backend-customization/models.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docusaurus/docs/cms/backend-customization/models.md b/docusaurus/docs/cms/backend-customization/models.md index b129bbce2c..491136c93f 100644 --- a/docusaurus/docs/cms/backend-customization/models.md +++ b/docusaurus/docs/cms/backend-customization/models.md @@ -99,6 +99,11 @@ The `info` key in the model's schema describes information used to display the m | `icon` | String | Name of the [Strapi icon](https://github.com/strapi/design-system) used to represent the model in the admin panel | | `preview` | String | Path or URL of an image used to represent a component in the admin panel.

Components only. See [Component preview images](#component-preview-images). | +:::note +This `preview` parameter is unrelated to the [Preview feature](/cms/features/preview). +That feature previews front-end content, and uses the `preview` object of `config/admin`. +::: + ```json title="./src/api/[api-name]/content-types/restaurant/schema.json" "info": { From 45a1b407d3732e27bfd3441cc97dbbd43284738e Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Thu, 27 Aug 2026 11:01:12 +0200 Subject: [PATCH 5/6] Warn that Media Library images cannot be used as component previews The public middleware does not serve /uploads/, so an image uploaded through the Media Library silently fails as a preview. The consequence was left for readers to infer. --- docusaurus/docs/cms/backend-customization/models.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docusaurus/docs/cms/backend-customization/models.md b/docusaurus/docs/cms/backend-customization/models.md index 491136c93f..f6a3c114b7 100644 --- a/docusaurus/docs/cms/backend-customization/models.md +++ b/docusaurus/docs/cms/backend-customization/models.md @@ -120,9 +120,13 @@ Components accept an optional `preview` parameter in their `info` object. It poi The `preview` parameter accepts: -- A root-relative path to an image placed in the project's `public` directory, for instance `/_component-screenshots/hero-section.png`. The image is then served by the [`public` middleware](/cms/configurations/middlewares#public), which does not serve paths starting with `/uploads/`. +- A root-relative path to an image placed in the project's `public` directory, for instance `/_component-screenshots/hero-section.png`. The image is served by the [`public` middleware](/cms/configurations/middlewares#public), which does not serve paths starting with `/uploads/`. - An absolute URL pointing to an external image host. +:::caution +[Media Library](/cms/features/media-library) images are served from `/uploads/`, so they cannot be used as preview images. Commit the file to `public` instead. +::: + ```json title="./src/components/sections/hero-section.json" { "info": { From a13e0d76e731222ecdd4e53bc8e3b592693652e1 Mon Sep 17 00:00:00 2001 From: Pierre Wizla <4233866+pwizla@users.noreply.github.com> Date: Thu, 27 Aug 2026 11:12:28 +0200 Subject: [PATCH 6/6] Cross-reference component preview images from both Components sections The section sits under Model information, next to the info table that lists preview, but a reader browsing either Components section had no path to it. --- docusaurus/docs/cms/backend-customization/models.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docusaurus/docs/cms/backend-customization/models.md b/docusaurus/docs/cms/backend-customization/models.md index f6a3c114b7..6729dc1c96 100644 --- a/docusaurus/docs/cms/backend-customization/models.md +++ b/docusaurus/docs/cms/backend-customization/models.md @@ -57,6 +57,9 @@ Component models can't be created with CLI tools. Use the [Content-type Builder] Components models are stored in the `./src/components` folder. Every component has to be inside a subfolder, named after the category the component belongs to (see [project structure](/cms/project-structure)). +Components also accept an optional preview image, displayed in the dynamic zone picker +instead of their icon (see [Component preview images](#component-preview-images)). + ## Model schema The `schema.json` file of a model consists of: @@ -608,6 +611,10 @@ Component fields create a relation between a content-type and a component struct } ``` +These parameters are set on the attribute of the content-type using the component. +Parameters set on the component itself, such as its preview image, belong to its own +`info` object (see [Component preview images](#component-preview-images)). + #### Dynamic zones Dynamic zones create a flexible space in which to compose content, based on a mixed list of [components](#components-json).