Global Contexts API reference

Global Context registration

The registration function takes a component and some metadata about it:

Copy

PLASMIC.registerGlobalContext(component: React.ComponentType<any>, meta: GlobalContextMeta): void

The first parameter component is the React component function or class that you want to register and use in the Studio.

The second parameter meta is an object containing metadata about the component. The object contains the following fields:

Field	Required?	Description
`name`	Yes	A unique string name used to identify this component. Each component should be registered with a different name. This name should be a valid javascript identifier, and we recommend picking a name that matches the component’s name in code.
`props`	Yes	An object specifying the props expected for this component. Each key of the object is the name of the prop, and the value is metadata about the prop. See Property types for more.
`displayName`	No	A human-friendly name to be displayed for the component in Studio UI; can contain spaces and punctuations.
`description`	No	A human-friendly description for what this component does; will be rendered as a helpful hint to Studio users.
`refProp`	No	The prop that receives and forwards a React `ref`. Plasmic only uses `ref` to interact with components in the editor, so it’s not used in the generated code. If not provided, the usual `ref` prop is used.
Codegen only:
`importPath`	Yes if using codegen	The path to be used when importing this component in the generated code. It can be the name of the npm package that contains the component (`antd`), or the path to the file in the project (relative to the `srcDir` root directory).
`isDefaultExport`	No	If true, then this component is the default export from `importPath`.
`importName`	No	If the component is not the default export, then it is a named export from `importPath`, named `importName`. Default to using `name` if not specified.

Prop Metadata

You can specify a lot of metadata about each prop of your global context; this helps Plasmic understand what each prop expects as an argument, so that Plasmic can generate the right UI in the Studio for users to configure these props.

Prop types

The main piece of prop metadata is the type of value expected for the prop. Here are the types we currently support:

Type	Prop value type	Description
`string`	string	Configured via a text input box in the Studio
`boolean`	boolean	Configured via a toggle switch in the Studio
`number`	number	Configured via a number input box or a slider
`code`	string	Configured via code editor in the Studio
`object`	JSON object or array	Configured via a text editor for arbitrary JSON values, including objects or arrays
`choice`	string or string[]	A select dropdown or a multi-select, for picking from an enumeration of possible string choices

As a convenient shorthand, if you don’t care about other prop metadata, then you can just pass in the type string as the prop metadata:

Copy

registerGlobalContext(MyComponent, {
  name: 'MyComponent',
  props: {
    color: 'string'
  }
});

Common options

Here are the common options you can specify in the prop metadata object. Most of them are optional, but specifying them will help Plasmic understand them better, and make them easier to use for Studio users.

Field	Required?	description
`type`	Yes	One of the supported prop types
`defaultValue`	No	The default value that should be provided to the prop. If not present, and no value is passed when the component is instantiated, Plasmic won’t provide any value. For slots, the default value can be an “element” or array of elements; see element types.
`defaultValueHint`	No	A value that is like a default value, but not actually used. Instead, it is shown as a placeholder when possible in the configuration control.
`editOnly`	No; defaults to false	A boolean indicating whether the values passed to that prop should only be used in the Studio, and not in real generated code. For example, you might have props that are only there to support Studio editor usage (like a prop that turns off animations or auto-play in the Studio). Another common example is a prop like `value`, which “controls” the value of, say, a `TextInput` component; in the Studio, it may be useful to set the `value` to something to see how it looks, but you may not actually want to use it in the generated code. Instead, it may make sense to pass on this value along to an `uncontrolledProp`. Not applicable for `slot`s.
`uncontrolledProp`	No	This is only applicable if `editOnly` is true. If specified, then the value that is set for this prop will instead be passed on to a prop with this name instead. This is useful when you have a controlled/uncontrolled pair of props, like `value` and `defaultValue`; in the Studio, you’d want to be able to set `value` to see how it looks, but when generating code, you may want to pass the value as `defaultValue` instead.

Type-specific options

Some additional options are only relevant to specific types:

`choice`

Field	Required?	description
`options`	Yes	Either a `string[]` that the user can choose from, or a `{value: string \| number \| boolean, label: string}[]` where the value is what’s ultimately passed into the prop.
`multiSelect`	No	If true, then allows selection of multiple options. The selection is to the prop as an array of strings.

`number`

Field	Required?	description
`control`	No; defaults to `default`	Either `default` or `slider`. If `default`, then Studio will render a default number input for configuring this prop. If `slider`, then Studio will render a number slider.
`min`	Yes if `slider`	Specifies the minimum value allowed.
`max`	Yes if `slider`	Specifies the maximum value allowed.
`step`	No	A number to indicate the step between consecutive values in the slider. If not specified, a default value will be computed based on the range `[min, max]`.

`string`

Field	Required?	description
`control`	No; defaults to `default`	Either `default` or `large`. If `default`, then Studio will render a default text input for configuring this prop. If `large`, then Studio will render a larger text editor with file uploader.

`code`

Field	Required?	description
`lang`	Yes	The code language for syntax highlighting and autocomplete. Allowed values are `css`, `html`, `javascript` and `json`.

Was this page helpful?

Give feedback on this page