Rendering Plasmic components
Once you have fetched the designs from Plasmic, you are ready to render it in your React application using <PlasmicRootProvider />
and <PlasmicComponent />
.
<PlasmicRootProvider />
This component should sit near the root of your application. It provides information to the <PlasmicComponent />
components you have throughout your app.
It takes these props:
Prop | Description |
---|---|
loader | Instance of PlasmicComponentLoader you created via initPlasmicLoader() |
prefetchedData | If you have prefetched data via fetchComponentData() , you can pass it here; <PlasmicComponent /> will avoid fetching data dynamically if it can find the data it needs in the prefetched data. |
prefetchedQueryData | If you have prefetched query data via extractPlasmicQueryData() , you can pass it here; usePlasmicQuereyData will avoid fetching data dynamically if it can find the data it needs in the prefetched data. |
suspenseForQueryData | Specifies whether usePlasmicQueryData() should be operating in suspense mode. |
globalVariants | You can activate the Plasmic global variants, like globalVariants={[{name: 'Theme', value: 'dark'}]} |
globalContextsProps | You can override the props for your global contexts, like globalContextsProps={{embedCssProps: {css: "/* CSS snippet */"}}} |
Link | You can override the default component that’s used for links, to customize link behavior. For instance, Link={MyCustomLinkComponent} . |
Head | You can override the default component that’s used for overriding page Head metadata. For instance, if using react-helmet , you can pass in Head={Helmet} . |
skipCss | If true, will not include CSS for components. You may want to do this if you are for some reason nesting PlasmicRootProviders; in that case, you’d only need CSS injected by the outermost PlasmicRootProvider. |
skipFonts | If true, will not include @import CSS to load remote fonts. You may want to do this if you are already loading the fonts you need yourself. |
skipHead | If true, will not generate next/head elements that override the page HTML head metadata. |
<PlasmicComponent />
This component renders a specific component designed in Plasmic. If the data is available (either already fetched or is provided as prefetchedData
for <PlasmicRootProvider/>
), then it is rendered immediately; otherwise, it renders null
while it fetches data.
Prop | Description |
---|---|
component | Either the name of the component or the path of the page component |
projectId | If there are multiple components of the same name across projects you are using, you can pass this in to disambiguate |
componentProps | Props to pass to the component to activate variants, specify slot contents, or attach event handlers. See here for details. |
forceOriginal | If you used registerComponent() , then if the name matches a registered component, that component is used. If you want the Plasmic-generated component instead, specify forceOriginal . You usually want this when you are doing component substitution to attach behavior and state to Plasmic-generated components. |
Customizing your component with componentProps
When you render a component using <PlasmicComponent />
, you can use the componentProps
prop to control which variants to activate, which slots to fill with what content, and which elements to instrument with real data or event handlers.
There are four classes of props that you can pass to componentProps
,
described in the next sections.
Variant props
Component variants are either simple standalone “toggle” variants, or they are organized into groups. For example, in a Button
component, we may have a variant group role
that includes primary
and secondary
variants, or a size
group that includes small
and large
variants. Often the groups are single-choice — you only allow one variant per group to be active. But sometimes it makes sense for them to be multi-choice — for example, a Button
component may have a variant group withIcons
that has options prefix
and suffix
, both of which can be true at the same time.
Each toggle variant and each variant group is a prop.
- For toggle variants, you can pass in
true
if you want it activated. - For single-choice variant groups, you can pass in the name of the variant you want to activate, or
undefined
if none should be activated. - For multi-choice variant groups, you can pass in an array of variant names, or a object of variant names mapping to true or false.
Example:
// Passing in booleans to turn on `isLoading` variant.<PlasmicComponentcomponent="Button"componentProps={{isLoading: true}}/>// Passing in literals to turn on `role` and `withIcons` variants<PlasmicComponentcomponent="Button"componentProps={{role: "primary",withIcons: ["prefix", "suffix"]}}/>// Turning on variants conditionally<PlasmicComponentcomponent="Button"componentProps={{role: (isPrimary() ? 'primary' :isSecondary() ? 'secondary' :undefined),withIcons:{prefix: hasPrefixIcon(),suffix: hasSuffixIcon()}}}/>
The variants prop
You can also combine all the variants you want to activate into a single variants
key:
<PlasmicComponentcomponent="Button"componentProps={{variants: {role: isPrimary() ? 'primary' : isSecondary() ? 'secondary' : undefined,withIcons: {prefix: hasPrefixIcon(),suffix: hasSuffixIcon()}}}}/>
Slot Props
You can also specify content for slots defined for the component. For example, a Button
component might have slots that correspond to the button text (children
), the prefix icon, and the suffix icon:
<PlasmicComponentcomponent="Button"componentProps={{prefixIcon: <TrashIcon />,children: 'Hello!'}}/>
You can also combine all the slot content you want to use into a single args
key:
<PlasmicComponentcomponent="Button"componentProps={{args: {prefixIcon: ...,suffixIcon: ...,children: "Hello!"}}}/>
Override props
The component as designed in Plasmic creates a tree of elements that corresponds to the tree of layers you see in Plasmic. The override props allow you to customize this tree of elements exactly as you see fit to make your component come alive. You can modify the props used for each element, attach event handlers, override rendered content, wrap elements in other React components, and more. We want you to have total control in making the element tree exactly what you want.
You reference the element you want to override by its name; so if you want to override an element, you must first name that element in Plasmic.
For example, for the Button component, you might want to override its root
element to attach click handlers:
<PlasmicComponentcomponent="Button"componentProps={{root: {props: {onClick: () => alert('I got clicked!')}}}}/>
Or maybe you want to render the Button as a link instead:
<PlasmicComponentcomponent="Button"componentProps={{root: {as: 'a',props: {href: 'https://plasmic.app'}}}}/>
The object you pass into the named node (“root”) above is the “Override object”. The Override object supports the following properties; you can mix and match them as needed:
props
Object of props to use for that element. Note that the element may be a normal HTML tag — in which case you can pass in HTML attributes — or a component — in which case you can pass in component props. For example,
{props: {title: user.name,onClick: () => ...,// etc.}}
as
The React.ElementType
to use to render this element. This can be an HTML tag like “a” for links, or a React component. This element will then be rendered with that element type. For example,
{as: "a",props: {href: ...}}
render
A function that takes in the props and the component type that would be rendered, and returns a ReactNode
. Doing this will completely replace this element with whatever is returned from the render function.
For example, this is a no-op (will behave as if no render function was specified):
{render: (props, Component) => <Component {...props} />;}
You can adjust the rendering in various ways:
{render: (props, Component) => (<Wrapper><Component className={props.className} value={value} onChange={handleChange} /></Wrapper>);}
You can swap in completely different content for this element:
{render: (props, Component) => <TotallyDifferentComponent />;}
You can also return null if you don’t want to render this element at all:
{render: (props, Component) => null;}
If you pass in a render
function, then props
and as
are ignored.
wrap
A function that takes in the rendered ReactNode
for this element, and returns another ReactNode
. This is useful if you just want to wrap this element in something, like a context provider. For example,
{wrap: node => <Context.Provider value={…}>{node}</Context.Provider>}
wrapChildren
A function that takes in the rendered children for this element, and returns another ReactNode
. This is useful if you want to append or prepend some custom content as a child of this element. For example, to implement an accessible “checkbox”, you may want to sneak in a visually hidden input element that’s not actually in the design:
{// insert a visually hidden checkbox input as the first childwrapChildren: (children) => (<><input className="visually-hidden" type="checkbox" />{children}</>);}
If you are planning to iterate over children
, note that Plasmic-generated code will sometimes wrap elements in React.Fragment
s. Therefore, instead of using React.Children.map()
, you should consider using something like react-keyed-flatten-children
, which will flatten fragments for you.
Override object shorthands
Instead of passing in a full Override object as specified above, you can instead use one of these shorthands:
- An object of prop overrides — if you pass in an object without any of the known keys above (
props
,as
,render
,wrap
, andwrapChildren
), we interpret that object as just a props override, equivalent to passing in{props: …}
. - A
ReactNode
— we interpret this as the children override, equivalent to{props: {children: …}}
. - A function — we interpret this as the
render
override, equivalent to{render: …}
.
Root override props
Any additional props you pass into componentProps
are interpreted as an override for the root element. For example, instead of using the root
prop as we did before, we can directly set the overrides like this:
<PlasmicComponentcomponent="Button"// This is interpreted as a prop override for the `root` elementcomponentProps={{ onClick: () => alert('I got clicked!') }}/>
Exploring the componentProps
you can use
You can explore exactly what componentProps
you can use for each component in Plasmic’s API explorer. You can get there by going to your project in Plasmic, clicking on the “Code” button in the upper-right, and selecting “Loader” as the integration scheme.
Have feedback on this page? Let us know on our forum.