Global Contexts API reference

Global Context registration

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

plasmic-init.ts
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:

FieldRequired?Description
nameYesA 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.
propsYesAn 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.
displayNameNoA human-friendly name to be displayed for the component in Studio UI; can contain spaces and punctuations.
descriptionNoA human-friendly description for what this component does; will be rendered as a helpful hint to Studio users.
refPropNoThe 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:
importPathYes if using codegenThe 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).
isDefaultExportNoIf true, then this component is the default export from importPath.
importNameNoIf 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:

TypeProp value typeDescription
stringstringConfigured via a text input box in the Studio
booleanbooleanConfigured via a toggle switch in the Studio
numbernumberConfigured via a number input box or a slider
codestringConfigured via code editor in the Studio
objectJSON object or arrayConfigured via a text editor for arbitrary JSON values, including objects or arrays
choicestring 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.

FieldRequired?description
typeYesOne of the supported prop types
defaultValueNoThe 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.
defaultValueHintNoA value that is like a default value, but not actually used. Instead, it is shown as a placeholder when possible in the configuration control.
editOnlyNo; defaults to falseA 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 slots.
uncontrolledPropNoThis 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

FieldRequired?description
optionsYesEither 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.
multiSelectNoIf true, then allows selection of multiple options. The selection is to the prop as an array of strings.

number

FieldRequired?description
controlNo; defaults to defaultEither 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.
minYes if sliderSpecifies the minimum value allowed.
maxYes if sliderSpecifies the maximum value allowed.
stepNoA 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

FieldRequired?description
controlNo; defaults to defaultEither 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

FieldRequired?description
langYesThe code language for syntax highlighting and autocomplete. Allowed values are css, html, javascript and json.
Was this page helpful?

Give feedback on this page