strapi-guided-tours

Strapi 5 plugin that lets you attach text descriptions and optional media to Content Manager fields, then surface them as info tooltips and guided tours while editors work on entries.

Installation

yarn add strapi-guided-tours
# or: npm install strapi-guided-tours

Enable the plugin in config/plugins.ts:

export default () => ({
  'guided-tours': {
    enabled: true,
  },
});

The npm package name is strapi-guided-tours; the Strapi plugin id remains guided-tours (from strapi.name in package.json).

Requires @strapi/plugin-upload (Media Library) for optional field media.

Features

• Configure per content type — pick a collection or single type, then map descriptions (and media) to its edit-view fields.
• Optional media — attach an image, video, audio, or file from the Media Library; previews appear in tooltips alongside the text.
• Info icons in the Content Manager — configured fields show an ℹ️ icon next to the label. Click it to open a popover with the description and media preview.
• Numbered / ordered tours — enable “Make it numbered” to drag-and-drop field order; a side-panel tour walks editors through fields in that sequence using driver.js.

Requirements

• Strapi 5..+

Usage

1. Open the plugin

In the Strapi admin sidebar, go to Guided Tours (plugin id: guided-tours).

2. Create or edit a configuration

1. Click Create new fields description (or edit an existing content type from the list).
2. Select a content type.
3. Toggle Make it numbered if you want drag-and-drop ordering and a guided tour in the Content Manager.
4. For each row, choose a field, enter a description, and optionally attach media.
5. Click Save.

3. See descriptions in the Content Manager

Open any entry for a configured content type. Fields with a description and/or media show an info icon next to the label. Click the icon to view the popover.

When numbering is enabled, the edit view side panel includes a Field descriptions tour button that steps through configured fields in order.

Data storage

Field descriptions are stored as Strapi collection-type data. The plugin defines a hidden content type plugin::guided-tours.field-description (not visible in the Content Manager or Content-Type Builder).

| Attribute | Type | Description | | ---------------- | ------- | ------------------------------------------------ | | contentTypeUid | string | Target content type UID (e.g. api::article.article) | | fieldName | string | Field name on the edit layout | | description | text | Help text shown in tooltips | | media | media | Optional single file (images, files, videos, audios) | | sortOrder | integer | Order index when numbering is enabled | | ordered | boolean | Whether this content type uses numbered ordering |

Media is linked through Strapi’s standard upload relation (files_related_mph), the same mechanism used by media fields on regular content entries.

All persistence goes through strapi.documents('plugin::guided-tours.field-description') with populate: ['media'] on reads.

API

The plugin exposes REST endpoints under /guided-tours/configurations:

| Method | Path | Description | | -------- | --------------------------------- | ------------------------------ | | GET | /guided-tours/configurations | List all field descriptions | | GET | /guided-tours/configurations/:id| Get one by document id | | POST | /guided-tours/configurations | Create one or many for a type | | PUT | /guided-tours/configurations/:id| Update a field description | | DELETE | /guided-tours/configurations/:id| Delete a field description |

Create body (batch):

{
  "contentTypeUid": "api::article.article",
  "ordered": true,
  "fields": [
    {
      "fieldName": "title",
      "description": "The headline shown on the homepage.",
      "media": 1
    }
  ]
}

Development

yarn build          # build admin + server bundles
yarn watch          # rebuild on file changes
yarn watch:link     # watch + link into a Strapi app
yarn verify         # verify plugin package
yarn test:ts:front  # typecheck admin
yarn test:ts:back   # typecheck server

Project layout

guided-tours/
  admin/src/
    components/       # Media picker, tooltips, tour UI, DZ portals
    hooks/            # useFieldDescriptions (shared cache)
    pages/            # HomePage (list), CreatePage (configure)
    contentManagerHooks/
  server/src/
    content-types/    # field-description schema
    controllers/      # configurations API
    services/         # fields-descriptions service
    routes/

License

MIT