Global Contexts

Global Contexts are React Components that will be used to pass data through all your artboards via context without the need to add it manually. Once you have your app host page set up, you can now tell Plasmic about the custom components you want to use in the Studio, by registering them.

Component registration

The global context components can be registered just like normal code components.

1. The actual React component function or class, so that Plasmic can actually instantiate and render those components
2. Component metadata, like its name and its props, so that Plasmic can generate the control UI in the right panel for Plasmic users to configure the component props.

For example,

import ProductContext from '../components/ProductCard';

export const PLASMIC = initPlasmicLoader(...);

PLASMIC.registerGlobalContext(ProductContext, {
  name: "ProductContext",
  props: {
    // Simple scalar props
    tokenId: 'string',
    darkMode: 'boolean',
    
    // Some props can take an enum of options
    productFilter: {
      type: 'choice',
      options: ['shirts', 'boots', 'jackets']
    }
    
    // Some props can take an arbitrary JSON object
    config: 'object',
  }
});

Visit the Global Context Registration API page to learn more about all the metadata you can specify when you register your component.

Use your global contexts in Studio!

Once you have finished registering your global contexts, make sure your changes are available on your app host, and reload your Plasmic project. You should see your global contexts now show up on the Project Settings tab.

Evolving global contexts over time

You can continue updating the code for your code components, and Plasmic will always use whatever is made available on the app host page.

However, occasionally, you want to evolve the metadata for your code components — its name and its props. To do so, you should make the updates to your registerGlobalContext() call, deploy your update to your app host, and then reload the Plasmic project using that app host; Plasmic will then read the new metadata, and update accordingly.

There are a few caveats to be aware of as you make your updates:

Renaming components

When you change the name from A to B, the next time you open a project containing A, Plasmic Studio will remove the instance of A and add a new instance of B. Note that this removes all existing arguments/values passed into that prop.

Changing props

Changing the type of a prop will prompt you to confirm removing usages of the old prop. Note that this removes all existing arguments/values passed into that prop.

Changing the type or name of a prop in a way that carries over all old values passed in for that prop is not yet supported. Tell us if that’s something you’d like to see.

Adding new global contexts and props

Since these are non-destructive changes, these will immediately take effect in the project without further user interaction.

Using Global Context in codegen

When generating the code for your project using Codegen, each project that has global contexts will have a PlasmicGlobalContextsProvider file. By default, each page will be wrapped in the GlobalContextsProvider from it’s project, but you can change this setting by changing the wrapPagesWithGlobalContexts flag in your plasmic.json file.

Prop override

You can override the props that you pass to your global contexts in both the Headless API and in Codegen.

<PlasmicRootProvider
  loader={PLASMIC}
  globalContextsProps={{
    productContextProps: { tokenId: 'token-id' }
  }}
>
  <PlasmicComponent component="YourPage" />
</PlasmicRootProvider>

Give feedback on this page