Static CMS exposes a window.CMS global object that you can use to register custom widgets via registerWidget. The same object is also the default export if you import Static CMS as an npm module.

React Components Inline

The registerWidget requires you to provide a React component. If you have a build process in place for your project, it is possible to integrate with this build process.

However, although possible, it may be cumbersome or even impractical to add a React build phase. For this reason, Static CMS exposes some constructs globally to allow you to create components inline: h (alias for React.createElement) as well some basic hooks (useState, useMemo, useEffect, useCallback).

Register Widget

Register a custom widget.

// Using global window object
CMS.registerWidget(name, control, [preview], [{ schema }]);

// Using npm module import
import CMS from '@staticcms/core';

CMS.registerWidget(name, control, [preview], [{ schema }]);

Params

Control Component

The react component that renders the control. It receives the following props:

Query

query allows you to search the entries of a given collection. It accepts the following props:

Preview Component

The react component that renders the preview. It receives the following props:

Options

Register widget takes an optional object of options. These options include:

Example

const CategoriesControl = ({ label, value, field, onChange }) => {
  const separator = useMemo(() => field.separator ?? ', ', [field.separator]);

  const handleChange = useCallback((e) => {
    onChange(e.target.value.split(separator).map(e => e.trim()));
  }, [separator, onChange]);

  return h('div', {}, {
    h('label', { for: 'inputId' }, label),
    h('input', {
      id: 'inputId',
      type: 'text',
      value: value ? value.join(separator) : '',
      onChange: handleChange,
    })
  });
};

const CategoriesPreview = ({ value }) => {
  return h(
    'ul',
    {},
    value.map((val, index) => {
      return h('li', { key: index }, val);
    }),
  );
};

const schema = {
  properties: {
    separator: { type: 'string' },
  },
};

CMS.registerWidget('categories', CategoriesControl, CategoriesPreview, { schema });

import CMS from '@staticcms/core';

const CategoriesControl = ({ label, value, field, onChange }) => {
  const separator = useMemo(() => field.separator ?? ', ', [field.separator]);

  const handleChange = useCallback(
    e => {
      onChange(e.target.value.split(separator).map(e => e.trim()));
    },
    [separator, onChange],
  );

  return (
    <div>
      <label for="inputId">{label}</label>
      <input
        id="inputId"
        type="text"
        value={value ? value.join(separator) : ''}
        onChange={handleChange}
      />
    </div>
  );
};

const CategoriesPreview = ({ value }) => {
  return (
    <ul>
      {value.map((val, index) => {
        return <li key={index}>{value}</li>;
      })}
    </ul>
  );
};

const schema = {
  properties: {
    separator: { type: 'string' },
  },
};

CMS.registerWidget('categories', CategoriesControl, CategoriesPreview, { schema });

import CMS from '@staticcms/core';

import type { WidgetControlProps, WidgetPreviewProps } from '@staticcms/core';

interface CategoriesField {
  widget: 'categories';
}

const CategoriesControl = ({
  label,
  value,
  field,
  onChange,
}: WidgetControlProps<string[], CategoriesField>) => {
  const separator = useMemo(() => field.separator ?? ', ', [field.separator]);

  const handleChange = useCallback(
    e => {
      onChange(e.target.value.split(separator).map(e => e.trim()));
    },
    [separator, onChange],
  );

  return (
    <div>
      <label for="inputId">{label}</label>
      <input
        id="inputId"
        type="text"
        value={value ? value.join(separator) : ''}
        onChange={handleChange}
      />
    </div>
  );
};

const CategoriesPreview = ({ value }: WidgetPreviewProps<string[], CategoriesField>) => {
  return (
    <ul>
      {value.map((val, index) => {
        return <li key={index}>{value}</li>;
      })}
    </ul>
  );
};

const schema = {
  properties: {
    separator: { type: 'string' },
  },
};

CMS.registerWidget('categories', CategoriesControl, CategoriesPreview, { schema });

admin/config.yml (or admin/config.js)

collections:
  - name: posts
    label: Posts
    folder: content/posts
    fields:
      - name: title
        label: Title
        widget: string
      - name: categories
        label: Categories
        widget: categories
        separator: __

collections: [
  {
    name: 'posts',
    label: 'Posts',
    folder: 'content/posts',
    fields: [
      {
        name: 'title'
        label: 'Title'
        widget: 'string'
      },
      {
        name: 'categories'
        label: 'Categories'
        widget: 'categories'
        separator: '__'
      }
    ]
  }
]

Advanced field validation

All widget fields, including those for built-in widgets, include basic validation capability using the required and pattern options.

With custom widgets, the widget can also optionally pass in a validator method to perform custom validations, in addition to presence and pattern. The validator function will be automatically called, and it can return either a boolean value, an object with a type and error message or a promise.

Examples

No Errors

const validator = () => {
  // Do internal validation
  return true;
};

Has Error

const validator = () => {
  // Do internal validation
  return false;
};

Error With Type

const validator = () => {
  // Do internal validation
  return { type: 'custom-error' };
};

Error With Type and Message

Useful for returning custom error messages

const validator = () => {
  // Do internal validation
  return { type: 'custom-error', message: 'Your error message.' };
};

Promise

You can also return a promise from validator. The promise can return boolean value, an object with a type and error message or a promise.

const validator = () => {
  return this.existingPromise;
};

Interacting With The Media Library

If you want to use the media library in your custom widget you will need to use the useMediaInsert and useMediaAsset hooks.

• useMediaInsert – Takes the current url to your media, details about your field (including a unique ID) and a callback method for when new media is uploaded. If you want to select folders instead of files, set the forFolder variable in options.
• useMediaAsset – Transforms your stored url into a usable url for displaying as a preview.

const FileControl = ({ collection, field, value, entry, onChange }) => {
  const handleChange = ({ path }) => {
    onChange(path);
  };

  const handleOpenMediaLibrary = useMediaInsert(value, { collection, field, controlID }, onChange);

  const assetSource = useMediaAsset(value, collection, field, entry);

  return [
    h('button', { type: 'button', onClick: handleOpenMediaLibrary }, 'Upload'),
    h('img', { role: 'presentation', src: assetSource }),
  ];
};

import useMediaAsset from '@staticcms/core/lib/hooks/useMediaAsset';
import useMediaInsert from '@staticcms/core/lib/hooks/useMediaInsert';

const FileControl = ({ collection, field, value, entry, onChange }) => {
  const handleChange = ({ path }) => {
    onChange(path);
  };

  const handleOpenMediaLibrary = useMediaInsert(
    value,
    { collection, field, controlID },
    handleChange,
  );

  const assetSource = useMediaAsset(value, collection, field, entry);

  return (
    <>
      <button type="button" onClick={handleOpenMediaLibrary}>
        Upload
      </button>
      <img role="presentation" src={assetSource} />
    </>
  );
};

import useMediaAsset from '@staticcms/core/lib/hooks/useMediaAsset';
import useMediaInsert from '@staticcms/core/lib/hooks/useMediaInsert';

import type { WidgetControlProps, MediaPath } from '@staticcms/core/interface';
import type { FC } from 'react';

const FileControl: FC<WidgetControlProps<string, MyField>> = ({
  collection,
  field,
  value,
  entry,
  onChange,
}) => {
  const handleChange = ({ path }: MediaPath) => {
    onChange(path);
  };

  const handleOpenMediaLibrary = useMediaInsert(
    internalValue,
    { collection, field, controlID },
    onChange,
  );

  const assetSource = useMediaAsset(value, collection, field, entry);

  return (
    <>
      <button type="button" onClick={handleOpenMediaLibrary}>
        Upload
      </button>
      <img role="presentation" src={assetSource} />
    </>
  );
};