import Prerequisite from '/docs/snippets/plugins-development-create-plugin-prerequisite-admin-panel.md'
import InjectionVsCmApis from '/docs/snippets/injection-zones-vs-content-manager-apis.md'

Content Manager APIs#

Content Manager APIs are part of the Admin Panel API. They are a way for Strapi plugins to add content or options to the Content Manager. The Content Manager APIs allow you to extend the Content Manager by adding functionality from your own plugin, just like you can do it with Injection zones.

General information#

Strapi 5 provides 4 Content Manager APIs, all accessible through app.getPlugin('content-manager').apis.
All the Content Manager APIs share the same API shape and must use components.

Injection zones vs. Content Manager APIs#

API shape#

All Content Manager APIs works in the same way: to use them, call them on your plugin's bootstrap() function, in 2 possible ways:

• Passing an array with what you want to add. For example, the following code would add the ReleasesPanel at the end of the current EditViewSidePanels:

  ⧉

  const apis = app.getPlugin('content-manager').apis;
  
  apis.addEditViewSidePanel([ReleasesPanel]);
  

  ⧉

  import type { ContentManagerPlugin } from '@strapi/content-manager/strapi-admin';
  
  const apis =
    app.getPlugin('content-manager').apis as ContentManagerPlugin['config']['apis'];
  
  apis.addEditViewSidePanel([ReleasesPanel]);
  

• Passing a function that receives the current elements and return the new ones. This is useful if, for example, you want to add something in a specific position in the list, like in the following code:

  ⧉

  const apis = app.getPlugin('content-manager').apis;
  
  apis.addEditViewSidePanel((panels) => [SuperImportantPanel, ...panels]);
  

  ⧉

  const apis =
    app.getPlugin('content-manager').apis as ContentManagerPlugin['config']['apis'];
  
  apis.addEditViewSidePanel((panels) => [SuperImportantPanel, ...panels]);
  

Components#

You need to pass components to the API in order to add things to the Content Manager.

Components are functions that receive some properties and return an object with some shape (depending on the function). Each component's return object is different based on the function you're using, but they receive similar properties, depending on whether you use a ListView or EditView API.

Properties include important information about the document(s) you are viewing or editing.

ListViewContext#

interface ListViewContext {
  /**
   * Will be either 'single-types' | 'collection-types'
   */
  collectionType: string;
  /**
   * The current selected documents in the table
   */
  documents: Document[];
  /**
   * The current content-type's model.
   */
  model: string;
}

EditViewContext#

interface EditViewContext {
  /**
   * This will only be null if the content-type
   * does not have draft & publish enabled.
   */
  activeTab: 'draft' | 'published' | null;
  /**
   * Will be either 'single-types' | 'collection-types'
   */
  collectionType: string;
  /**
   * Will be undefined if someone is creating an entry.
   */
  document?: Document;
  /**
   * Will be undefined if someone is creating an entry.
   */
  documentId?: string;
  /**
   * Will be undefined if someone is creating an entry.
   */
  meta?: DocumentMetadata;
  /**
   * The current content-type's model.
   */
  model: string;
}

Example:

Adding a panel to the sidebar can be done as follows:

const Panel = ({ 
  activeTab, 
  collectionType, 
  document, 
  documentId, 
  meta, 
  model 
}) => {
  return {
    title: 'My Panel',
    content: <p>I'm on {activeTab}</p>
  }
}

import type { PanelComponent, PanelComponentProps } from '@strapi/content-manager/strapi-admin';

const Panel: PanelComponent = ({ 
  activeTab, 
  collectionType, 
  document, 
  documentId, 
  meta, 
  model 
}: PanelComponentProps) => {
  return {
    title: 'My Panel',
    content: <p>I'm on {activeTab}</p>
  }
}

Available APIs#

addEditViewSidePanel#

Use this to add new panels to the Edit view sidebar, just like in the following example where something is added to the Releases panel:

addEditViewSidePanel(panels: DescriptionReducer<PanelComponent> | PanelComponent[])

PanelComponent#

A PanelComponent receives the properties listed in EditViewContext and returns an object with the following shape:

type PanelComponent = (props: PanelComponentProps) => {
  title: string;
  content: React.ReactNode;
};

PanelComponentProps extends the EditViewContext.

addDocumentAction#

Use this API to add more actions to the Edit view or the List View of the Content Manager. There are 3 positions available:

• header of the Edit view:

  

• panel of the Edit view:

  

• table-row of the List view:

  

addDocumentAction(actions: DescriptionReducer<DocumentActionComponent> | DocumentActionComponent[])

DocumentActionDescription#

The interface and properties of the API look like the following:

interface DocumentActionDescription {
    label: string;
    onClick?: (event: React.SyntheticEvent) => Promise<boolean | void> | boolean | void;
    icon?: React.ReactNode;
    /**
     * @default false
     */
    disabled?: boolean;
    /**
     * @default 'panel'
     * @description Where the action should be rendered.
     */
    position?: DocumentActionPosition | DocumentActionPosition[];
    dialog?: DialogOptions | NotificationOptions | ModalOptions;
    /**
     * @default 'secondary'
     */
    variant?: ButtonProps['variant'];
    loading?: ButtonProps['loading'];
}

type DocumentActionPosition = 'panel' | 'header' | 'table-row' | 'preview' | 'relation-modal';

interface DialogOptions {
    type: 'dialog';
    title: string;
    content?: React.ReactNode;
    variant?: ButtonProps['variant'];
    onConfirm?: () => void | Promise<void>;
    onCancel?: () => void | Promise<void>;
}
interface NotificationOptions {
    type: 'notification';
    title: string;
    link?: {
        label: string;
        url: string;
        target?: string;
    };
    content?: string;
    onClose?: () => void;
    status?: NotificationConfig['type'];
    timeout?: number;
}
interface ModalOptions {
    type: 'modal';
    title: string;
    content: React.ComponentType<{
        onClose: () => void;
    }> | React.ReactNode;
    footer?: React.ComponentType<{
        onClose: () => void;
    }> | React.ReactNode;
    onClose?: () => void;
}

addDocumentHeaderAction#

Use this API to add more actions to the header of the Edit view of the Content Manager:

addDocumentHeaderAction(actions: DescriptionReducer<HeaderActionComponent> | HeaderActionComponent[])

HeaderActionDescription#

The interface and properties of the API look like the following:

interface HeaderActionDescription {
  disabled?: boolean;
  label: string;
  icon?: React.ReactNode;
  type?: 'icon' | 'default';
  onClick?: (event: React.SyntheticEvent) => Promise<boolean | void> | boolean | void;
  dialog?: DialogOptions;
  options?: Array<{
    disabled?: boolean;
    label: string;
    startIcon?: React.ReactNode;
    textValue?: string;
    value: string;
  }>;
  onSelect?: (value: string) => void;
  value?: string;
}

interface DialogOptions {
  type: 'dialog';
  title: string;
  content?: React.ReactNode;
  footer?: React.ReactNode;
}

addBulkAction#

Use this API to add buttons that show up when entries are selected on the List View of the Content Manager, just like the "Add to Release" button for instance:

addBulkAction(actions: DescriptionReducer<BulkActionComponent> | BulkActionComponent[])

BulkActionDescription#

The interface and properties of the API look like the following:

interface BulkActionDescription {
  dialog?: DialogOptions | NotificationOptions | ModalOptions;
  disabled?: boolean;
  icon?: React.ReactNode;
  label: string;
  onClick?: (event: React.SyntheticEvent) => void;
  /**
   * @default 'default'
   */
  type?: 'icon' | 'default';
  /**
   * @default 'secondary'
   */
  variant?: ButtonProps['variant'];
}

addRichTextBlocks#

Use this API to register custom block types in the Blocks rich text field. Custom blocks appear in the toolbar dropdown alongside built-in ones.

addRichTextBlocks(blocks: RichTextBlocksStore | ((currentBlocks: RichTextBlocksStore) => RichTextBlocksStore))

The API accepts 2 call signatures:

• Passing an object: the provided blocks are merged into the existing blocks store.

  ⧉

  export default {
    register(app) {
      app.getPlugin('content-manager').apis.addRichTextBlocks({
        callout: {
          renderElement: (props) => <Callout {...props.attributes}>{props.children}</Callout>,
          icon: Information,
          label: { id: 'my-plugin.blocks.callout', defaultMessage: 'Callout' },
          matchNode: (node) => node.type === 'callout',
          isInBlocksSelector: true,
          handleConvert(editor) { /* use Slate Transforms to set node type */ },
          snippets: [':::callout'],
        },
      });
    },
  };
  

  ⧉

  import type { ContentManagerPlugin } from '@strapi/content-manager/strapi-admin';
  
  export default {
    register(app) {
      const apis =
        app.getPlugin('content-manager').apis as ContentManagerPlugin['config']['apis'];
  
      apis.addRichTextBlocks({
        callout: {
          renderElement: (props) => <Callout {...props.attributes}>{props.children}</Callout>,
          icon: Information,
          label: { id: 'my-plugin.blocks.callout', defaultMessage: 'Callout' },
          matchNode: (node) => node.type === 'callout',
          isInBlocksSelector: true,
          handleConvert(editor) { /* use Slate Transforms to set node type */ },
          snippets: [':::callout'],
        },
      });
    },
  };
  

• Passing a function: the function receives the current blocks store and must return the updated store. Use this form to remove or replace built-in blocks.

  ⧉

  export default {
    register(app) {
      app.getPlugin('content-manager').apis.addRichTextBlocks((currentBlocks) => {
        // Remove the built-in code block
        const { code: _removed, ...rest } = currentBlocks;
        return rest;
      });
    },
  };
  

  ⧉

  import type {
    ContentManagerPlugin,
    RichTextBlocksStore,
  } from '@strapi/content-manager/strapi-admin';
  
  export default {
    register(app) {
      const apis =
        app.getPlugin('content-manager').apis as ContentManagerPlugin['config']['apis'];
  
      apis.addRichTextBlocks((currentBlocks: RichTextBlocksStore) => {
        const { code: _removed, ...rest } = currentBlocks;
        return rest;
      });
    },
  };
  

Block definition#

Each entry in the blocks object is a block definition with the following properties:

The built-in block keys are: paragraph, heading-one, heading-two, heading-three, heading-four, heading-five, heading-six, list-ordered, list-unordered, image, quote, code, link, list-item.

Key handler example

Key handlers each receive the Slate editor instance. Use Slate's Transforms API to modify the document:

callout: {
  // ...
  handleEnterKey(editor) {
    // Exit the block on Enter and insert a new paragraph below
    Transforms.insertNodes(editor, { type: 'paragraph', children: [{ text: '' }] });
  },
  handleBackspaceKey(editor, event) {
    // Convert back to paragraph when backspacing in an empty callout
    Transforms.setNodes(editor, { type: 'paragraph' });
  },
  handleTab(editor) {
    // Increase indentation level on Tab
    Transforms.setNodes(editor, { indent: (editor.selection ? 1 : 0) });
  },
  handleShiftTab(editor) {
    // Decrease indentation level on Shift+Tab
    Transforms.setNodes(editor, { indent: 0 });
  },
},