Extension Wrapper

The UI Extension Wrapper does the actual communication and state synchronisation with GraphCMS, and must be in the parents tree of any component implementing the hook.

The <Wrapper /> requires 2 props:

  • A valid extensionUid
  • A valid declaration

QuickstartAnchor

import {
Wrapper,
FieldExtensionType,
FieldExtensionFeature,
} from '@graphcms/uix-react-sdk';
const YourCustomFieldHere = () => {
// Your UI extension code
};
const declaration = {
name: 'My custom field',
fieldType: FieldExtensionType.STRING,
extensionType: 'field',
features: [FieldExtensionFeature.FieldRenderer],
};
const Extension = () => {
const queryParams = new URLSearchParams(window.location.search);
const uid = queryParams.get('extensionUid');
<Wrapper uid={extensionUid} declaration={declaration}>
<YourCustomFieldHere />
</Wrapper>;
};

Extension UidAnchor

As multiple instances of the same extension can be used in the same screen, GraphCMS will add a unique ID in the query param extensionUid of the extension url.

You must handle fetching the extensionUid from the query string and pass this to the wrapper. It might look something like:

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

Extension DeclarationAnchor

The Extension Declaration is an object describing the extension, it's capabilities and configuration options.

When registering a new extension, GraphCMS will be load and validate this declaration and use it to build the configurations forms.

Declaration PropertiesAnchor

KeyTypeDescription
extensionTypeEnum (field,) (required)Type of Extension.
nameString (required)Display name for the Extension.
descriptionStringOptional description.
configConfigOptionsDefinitionOptional definition of global configuration options for this extension.

Config propertiesAnchor

You can use config properties to prompt the user when installing the plugin for additional settings that are made available to your UI extension.

KeyType
typeEnum(string, number,boolean) (required)
displayNameString
descriptionString
requiredBoolean
defaultValueany

In the example below we'll declare configuration for a STORE_ID and ACCESS_TOKEN.

const declaration = {
config: {
STORE_ID: {
type: 'string',
displayName: 'Store ID',
required: true,
},
ACCESS_TOKEN: {
type: 'string',
displayName: 'Store Access Token',
description: 'API access token for this UI extension',
required: true,
},
// ... rest of declaration props here
},
};

When installing the above with the configuration, it would look something like:

UI Extension Configuration
UI Extension Configuration

Did you find this page useful?

Your feedback helps us improve our docs, and product.