Strapi v5 - Plugin Generic Custom Fields

Powerful Strapi Plugin to easily create Custom Fields

A plugin for Strapi Headless CMS that provides a powerful and easy way to add custom fields to your Strapi entities.

Features

• Add custom fields to entities with a simple configuration.

What can it be used for?

• Create an Enum field with labels
• Fetch items from an API (with or without authentication)
• Fetch items from a local source (json file, database, etc.)

Roadmap

• Support pagination for fetching items
• Support for different field types (text, number, date, etc.)
• Validation rules for custom fields
• Any idea? Open an issue

Usage

To configure the Generic Custom Fields plugin, add your custom fields configuration to the plugin settings. Each custom field should follow this structure:

1type Config = {
2  customFields: Array<{
3    name: string;         // The unique name of the custom field.
4    description?: string; // A description for the custom field.
5    icon?: string;        // One of the supported StrapiIcon names, e.g. 'Alien', 'Archive', 'ArrowDown', etc.
6    inputSize?: {
7      default: 4 | 6 | 8 | 12; // Default input size.
8      isResizable: boolean;    // Whether the input size can be changed.
9    };
10    searchable?: boolean; // Whether the custom field is searchable (calls fetchItems with query).
11    fetchItems: ({ query: string | undefined }): { items: Item[] } | Promise<{ items: Item[] }>; // Function to fetch multiple items. This function is called on server-side.
12    fetchItem: ({ value: string }): Item | Promise<Item>; // Function to fetch a single item. This function is called on server-side.
13  }>,
14}
15type Item = {
16    value: string; // Unique identifier for the item. This is used to store the value of the custom field.
17    label: string; // Label of the item.
18};

This configuration allows you to define custom fields that can fetch items either synchronously or asynchronously. The fetchItems function is used to retrieve a list of items based on a query string that can be empty, while the fetchItem function retrieves a single item based on its value.

Example Configuration

1// config/plugins.ts
2import type { Config as GenericCustomFieldsConfig } from 'strapi-plugin-generic-custom-fields'
3
4export default () => ({
5  'generic-custom-fields': {
6    enabled: true,
7    config: {
8      customFields: [
9        { // Non Async Example (Enum with labels)
10          name: 'Category',
11          description: 'Select a category',
12          icon: 'PuzzlePiece',
13          inputSize: { default: 6, isResizable: true },
14          fetchItems: ({ query }) => {
15            return {
16              items: [
17                { value: 'fashion', label: 'Fashion' },
18                { value: 'beauty', label: 'Beauty' },
19                { value: 'electronics', label: 'Electronics' },
20                { value: 'home', label: 'Home' },
21                { value: 'sports', label: 'Sports' },
22                { value: 'toys', label: 'Toys' },
23                { value: 'books', label: 'Books' },
24                { value: 'automotive', label: 'Automotive' },
25              ]
26            }
27          },
28          fetchItem: ({ value }) => ({ value, label: value }),
29        },
30        { // Async Example (Fetch items from any API)
31          name: 'Star Wars Planet',
32          description: 'Select a Star Wars Planet',
33          icon: 'Earth',
34          fetchItems: async ({ query }) => {
35            const response = await fetch('https://swapi.info/api/planets', {
36              headers: {
37                // We can use an API token if needed since this is server-side code
38                Authorization: `Bearer ${process.env.SWAPI_TOKEN}`,
39              },
40            })
41            if (!response.ok) {
42              throw new Error(`Failed to fetch Star Wars planet items: ${response.status} ${response.statusText}`)
43            }
44            const data = await response.json() as { name: string, url: string }[]
45            return {
46              items: data.map((item) => ({ label: item.name, value: item.url })),
47            }
48          },
49          fetchItem: async ({ value }) => {
50            const response = await fetch(value)
51            if (!response.ok) {
52              throw new Error(`Failed to fetch Star Wars Planet item: ${response.status} ${response.statusText}`)
53            }
54            const data = await response.json() as { name: string, url: string }
55            return { label: data.name, value }
56          },
57        },
58      ],
59    } satisfies GenericCustomFieldsConfig,
60  },
61})