Code component substitution

You can use existing code components or design systems with Plasmic. For instance, you may want to enable Plasmic Studio users to:

  • Insert an element type not yet supported in Plasmic, such as videos.
  • Insert a complex component like a Google Maps widget, a rich text editor, or a WebGL animation.
  • Insert a data-connected component like a product gallery from your ecommerce store.
  • Use an existing component library or design system.

You cannot yet use code components in the Plasmic Studio editor, but you can create placeholder components and have them swapped out for the real thing from code.

The workflow is:

  1. Create a design-time placeholder for the existing code component you’re interested in. This is just for use in the Studio, and can be as accurate as you want it to be in mirroring what the real code component looks like.
  2. In code, substitute the existing code component for the design-time placeholder.
  3. Optionally use props, especially meta props and slots, to configure the behavior of the code component.

For instance, if you want to use a Google Maps widget:

  1. Paste a static screenshot of a Google Maps widget into your project, and turn it into a component called “GMaps.” Use this component wherever you want a real Google Maps widget.

  2. In code, rather than render the <PlasmicGMaps/> component inside the GMaps component, render a real Google Maps widget.

    // GMaps.tsx
    import { GoogleMap, LoadScript } from '@react-google-maps/api';
    
    interface GMapsProps {
      location: string;
      className?: string;
    }
    function GMaps({ location, className }: GMapsProps) {
      // Removed the default generated code of: return <PlasmicGMaps/>;
      const [lat, lng] = useResolvedLocation(location); // your own hook
      return (
        <LoadScript googleMapsApiKey="...">
          <GoogleMap center={{ lat, lng }} mapContainerClassName={className} zoom={10} />
        </LoadScript>
      );
    }
  3. In Plasmic Studio, on the GMaps component, add a meta prop location of type text. Plasmic Studio users can use this to identify a concrete location that the real Google Maps widget can read.

(Side note: @react-google-maps has blocking JS and/or layout shift on load. We recommend lazily loading the component on scrolling into view, or using a performance-optimized alternative such as Pigeon Maps.)

Adding component props

Components are customized via props. How do we enable the design-time placeholder component in Plasmic Studio to specify props to the code component it’ll be substituted by?

Meta props

You can explicitly add meta props to the placeholder component. Then, from any instance, you can pass a value for the prop. These are not used or reflected in any way in the design-time placeholder component; you’re simply attaching metadata to the component instance.

Later, when the code component is attached, these props will be forwarded to it.

The meta props have simple data types like text and number. As such these are appropriate when you have some simple data to pass in. Examples of this include:

  • a Google Maps widget has some location prop (as we’ve seen above).
  • a Product Card has a productId prop.
  • a Video component has a url prop.

Slots

However, some components have children or similar props, which take ReactNodes rather than data types like text or number.

Examples of this include:

  • a Button takes a children prop for its main text/content.
  • a Card component takes a title and children (main body content).

For these, you would pass in other visual elements for the props (i.e. they take ReactNodes). So in your placeholder component, you should create slots named children and title. Then you can visually manipulate the elements as usual in the Plasmic Studio editor.