Building UI Extensions

We'll get started building a UI extension using the React SDK.

To build the extension, you'll need to add @graphcms/uix-react-sdk to your project.

npm install @graphcms/uix-react-sdk

  yarn add @graphcms/uix-react-sdk

Start with importing the Wrapper component and useUiExtension hook from the library inside your React application, as well as the FieldExtensionType and FieldExtensionFeature enumerations.

import {
  Wrapper,
  useUiExtension,
  FieldExtensionType,
  FieldExtensionFeature,
} from '@graphcms/uix-react-sdk';

You'll now want to invoke the useUiExtension hook to get the value and onChange handler we'll pass to our custom field.

UI extensions can come in all shapes and sizes, and for the purposes of this guide, we'll explore using a simple HTML <input />.

const MyField = () => {
  const { value, onChange } = useUiExtension();

  return (
    <input
      value={value}
      onChange={({ target: { value: val } }) => onChange(val)}
    />
  );
};

Every UI extension must have a declaration. Custom fields must declare their type, name and features. The latter will communicate to GraphCMS which capabilities your app has.

This example app will only need the field renderer, so let's add it to the features array:

const declaration = {
  extensionType: 'field',
  fieldType: FieldExtensionType.STRING,
  name: 'My custom field',
  features: [FieldExtensionFeature.FieldRenderer],
};

Your app must be inside of the Wrapper component we imported earlier. Pass it the declaration that we have just composed, as a prop.

If you plan to create multiple UI extensions, you should use your application's router to mount extensions at different endpoints so you can install these separately. For example, you'll need to render <MyField /> at a specific route.

As you can probably tell from above, it's rather basic! But this covers the barebones setup you need to build your own component.

Now that we've written our UI extension, you'll need to deploy it to the web. Providers such as Vercel, Netlify, and Heroku provide one-click, and "deploy from GitHub" options to make this easier.