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 -E @graphcms/uix-react-sdk

You'll then want to import the Wrapper component, and useUiExtension hook from the library inside your React application, as well as the type FieldExtensionType. If you plan to create multiple UI extensions, you should use your applications router to mount extensions at different endpoints so you can install these separately.

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 handlers 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)}
/>
);
};

Next let's declare our UI extension type, and name:

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

If your UI extension has requires configuration from the user, such as API keys, you can declare that inside of the config options.

You'll need to get from the query params the extensionUid value that is passed when GraphCMS makes a request to your extension.

const Extension = () => {
const queryParams = new URLSearchParams(window.location.search);
const uid = queryParams.get('extensionUid');
return (
<Wrapper uid={uid} declaration={declaration}>
<MyField />
</Wrapper>
);
};

You'll then need to render <Extension /> at a specific route.

If you used Next.js, it would look a little like:

export default function MyFieldExtensionPage() {
const router = useRouter();
const { extensionUid } = router.query;
if (!extensionUid) return null;
const declaration = {
extensionType: 'field',
fieldType: FieldExtensionType.STRING,
name: 'My custom field',
features: [FieldExtensionFeature.FieldRenderer],
};
return (
<Wrapper uid={extensionUid} declaration={declaration}>
<MyField />
</Wrapper>
);
}

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

Now 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.

Did you find this page useful?

Your feedback helps us improve our docs, and product.