diff --git a/docusaurus/docs/cms/backend-customization/models.md b/docusaurus/docs/cms/backend-customization/models.md
index a89ce419ac..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:
@@ -96,6 +99,13 @@ 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). |
+
+:::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"
@@ -107,6 +117,35 @@ 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 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": {
+ "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.
@@ -572,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).
diff --git a/docusaurus/docs/cms/features/content-manager.md b/docusaurus/docs/cms/features/content-manager.md
index 2692df834f..0d1f5d15ea 100644
--- a/docusaurus/docs/cms/features/content-manager.md
+++ b/docusaurus/docs/cms/features/content-manager.md
@@ -426,6 +426,10 @@ 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.