Code components API reference

registerComponent

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

PLASMIC.registerComponent(
  component: React.ComponentType<any>,
  meta: ComponentMeta,
): 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:

Prop Metadata

You can specify a lot of metadata about each prop of your code component; 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:

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:

registerComponent(MyComponent, {
  name: 'MyComponent',
  props: {
    children: 'slot',
    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.

Type-specific options

Some additional options are only relevant to specific types:

choice

number

string

code

color

object

This type represents a JSON object. If you specify an optional schema for your object, the Studio will render a form for the user to fill out; else the user can type a JSON expression into a code editor.

registerComponent(FAQ, {
  name: 'FAQ',
  props: {
    content: {
      type: 'object',
      fields: {
        question: {
          type: 'string',
          displayName: "What's your question?"
        },
        answer: {
          type: 'richText'
        },
        color: {
          type: 'color'
        }
      }
    }
  }
});

array

This represents a JSON array. Currently, we only support having an array of object types, but there will be more in the future.

eventHandler

cardPicker

class

A css class name will be passed in as the prop value, which the code component should apply to the right element. The Plasmic Studio user will be able to configure what styles to add to the css class. This allows users to style specific parts of a code component.

For example, say I have a counter code component, and I want to allow the user to style the count and the button:

function Counter({ className, countClassName, buttonClassName }) {
  const [count, setCount] = React.useState(0);
  return (
    <div className={className} data-used={count > 0}>
      <div className={countClassName}>{count}</div>
      <button className={buttonClassName} onClick={() => setCount((c) => c + 1)}>
        Increment
      </button>
    </div>
  );
}

registerComponent(Counter, {
  name: 'Counter',
  props: {
    buttonClassName: {
      type: 'class',
      selectors: [
        // Plasmic Studio user can also in addition style the button's
        // hovered and pressed state
        {
          selector: ':hover',
          label: 'Hovered'
        },
        {
          selector: ':active',
          label: 'Pressed'
        }
      ]
    },
    countClassName: {
      type: 'class',
      selectors: [
        // You can also use a selector that uses the non-standard
        // :component and :self selectors, to refer to the component root
        // and the element receiving the class. Here, we are targeting
        // when the component root has data-used=true applied.
        {
          selector: `:component[data-used="true"] :self`,
          label: 'When used'
        }
      ],
      // We can limit what kind of styles can be applied to this element
      styleSections: ['typography']
    }
  }
});

styleSections

For places where you can control which style sections show up in the right pane of the Studio editor, you can use these values:

• typography — text styles
• sizing — width/height
• spacing — padding (margin is always available)
• background — background colors, images or gradients
• transform — css transforms
• transitions — css transitions
• layout — switch between vertical/horizontal stack, grid, and other layout settings
• overflow — container overflow behavior
• border — border and border-radius
• shadows — box-shadow
• effects — miscellaneous effects like cursor, filter, etc.
• visibility — opacity or display: none

selectors

When writing your css selector in the selector field, you can use standard css selectors like :hover or :first-child. But you can also use these special selectors:

• :component — selects the component root
• :self — selects the element with the class applied

For example, you can write a selector like :component[data-used="true"] :self, which will be active when the root element has data-used=true html attribute.

themeResetClass

A css class name will be passed in as this prop, which will apply the default styles configured in the Plasmic project, the default tag styles, and also include the definition of all the css variables. This is useful if your code component is rendering content outside of the normal DOM tree via React portals.

The Plasmic Studio user won’t actually see any configuration for this prop; this is purely for your code component to use.

function Modal({ themeResetClass, className, modalContent }) {
  const [show, setShow] = React.useState(false);
  return (
    <>
      <button className={className} onClick={() => setShow(true)}>
        Show
      </button>
      {ReactDOM.createPortal(<div className={`modal ${themeResetClass}`}>{modalContent}</div>, document.body)}
    </>
  );
}

registerComponent(Modal, {
  name: 'Modal',
  props: {
    modalContent: 'slot',
    themeResetClass: {
      type: 'themeResetClass'
    }
  }
});

slot

For slot props, We highly recommend always providing defaultValue! When the Studio user uses a code component, defaultValue fills up the slots with initial content that the user can then tweak and customize. Without it, the user may be looking at a confounding set of empty placeholder boxes. See what default content you can specify for your slots here.

renderPropParams

To pass specific arguments as render props to a slot, use the renderPropParams field. This field is an array of strings, with each string representing the name of an argument you want to pass to the render prop function.

const animals = [
  {
    "name": "Elephant",
    "habitat": "Savannah"
  },
  {
    "name": "Penguin",
    "habitat": "Antarctica"
  },
  {
    "name": "Kangaroo",
    "habitat": "Australian Outback"
  }
];

function MyComponent(props) {
  return (
    <div>
      {animals.map(item => (
        <p key={item.name}>{props.children(item)}</p>
      ))}
    </div>
  )
}

PLASMIC.registerComponent(MyComponent, {
  name: 'MyComponent',
  props: {
    children: {
      type: 'slot',
      renderPropParams: ["animal"],
    }
  }
});

In Studio, you can access the render prop arguments (specified by the renderPropParams field) inside the Data Picker modal, triggered from within the children slot content:

Here is the output on the canvas:

Prop control function

Where noted, instead of specifying a hard-coded value, you can instead specify a “prop control function” that dynamically returns the value to use based on current conditions.

A “prop control function” takes in two arguments:

• The component props for this component instance; this allows you to customize the value to use based on other props that are set for this instance.
• The component “context” set by your code component, which provides any other information that the component wants to pass in. Note that this “context” is not related to React Contexts.

Sometimes, your prop control function only needs access to the instance props to make its decisions. For instance, you can conditionally set hidden on a prop control based on the values of other props:

function Slider({
  start, end, hasEnd,
}: {
  hasEnd?: boolean
  start?: number,
  end?: number,
}) {
  return <div>...</div>;
}

registerComponent(ProductCard, {
  name: 'Slider',
  props: {
    hasEnd: 'boolean'
    start: 'number',
    end: {
      type: 'number',
      // `hidden` takes a prop control function
      hidden: props => !props.hasEnd,
    },
  }
});

Other times, it may also want to include other data, such as:

• Data that the component reads from a React Context.
• Data that the component fetches asynchronously.
• Data that the component computes.

For example, the options for your choice prop may depend on data passed down by some React Context. In that case, your code component can communicate this data to the control function. It does so by using a setControlContextData function that has been injected into your code component props:

function ProductCard({
  productId,
  setControlContextData
}: {
  productId?: string;
  // When rendered in Studio artboard, a `setControlContextData` function will
  // be injected as a prop. This function can relay any data you want, so you
  // define whatever type it accepts.
  setControlContextData?: (ctxData: { allProductSlugs: string[] }) => void;
}) {
  const { allProductSlugs } = React.useContext(StoreInfo);

  // Tell the prop control about what products are available
  // to choose from. We are just calling this for the side effect.
  setControlContextData?.({
    allProductSlugs
  });

  return <div>...</div>;
}

registerComponent(ProductCard, {
  name: 'ProductCard',
  props: {
    productId: {
      type: 'choice',
      options: (props, ctx) => {
        // Use the product slugs given to us from setControlContextData()
        return ctx.allProductSlugs;
      }
    }
  }
});

Notice it’s possible that the prop controls render before the component instance - in which case, the context data will be null, and the controls will re-render once new context data is provided.

Exposing component state

Code components can also participate in the interactions and state framework by exposing some metadata and a few props.

Writable states

Suppose we are registering a TextInput code component, which is controlled by the value prop. We can tell Plasmic that it has a state called value, like this:

function TextInput({ value, onChange, className }) {
  return (
    <div className={className}>
      <input value={value} onChange={(e) => onChange(e.target.value)} />
    </div>
  );
}

registerComponent(TextInput, {
  name: 'TextInput',
  props: {
    value: 'string',
    onChange: {
      type: 'eventHandler',
      argTypes: [{ name: 'value', type: 'string' }]
    }
  },
  states: {
    value: {
      // The state value is owned by the parent -- parent can control
      // the value of this state
      type: 'writable',
      // The type of state value
      variableType: 'text',
      // The prop name that controls this state
      valueProp: 'value',
      // The prop name for the event handler that is called whenever
      // this state changes
      onChangeProp: 'onChange'
      // The initial value of a writable state is sepecified as the
      // `defaultValue` for your valueProp
    }
  }
});

This tells Plasmic how to control the state (by passing in the right value to the value prop), and how to listen to state changes (by using the onChange prop).

When the user uses a TextInput in Plasmic studio, they will see that each instance has a value state, and they’ll be able to read and update that state when rendering or in an interaction.

The variableType can be one of text, number, boolean, array, object.

Read-only states

Some states are controlled by the code component, but you still want to expose it to outside the component. For example, consider a DataTable code component that wants to expose the selectedRow:

function DataTable({data, onSelectedRowChange}) {
  ...
}

registerComponent(DataTable, {
  name: "DataTable",
  props: {
    data: {
      type: "object"
    },
    onSelectedRowChange: {
      type: "eventHandler",
      argTypes: [{name: "row", type: "object"}]
    }
  },
  states: {
    selectedRow: {
      // This state cannot be controlled by the parent -- so can only be read
      type: "readonly",
      variableType: "object",

      // Only need to specify an onChangeProp, not a valueProp
      onChangeProp: "onSelectedRowChange"
    }
  }
})

Initial state values

Because the parent component depends on the onChangeProp to communicate the state value, and because by convention, your code component likely does not call the onChangeProp upon initial rendering, and only upon user interaction, it is a good idea to also specify an initial state value, so that the parent component knows what the state value is, even before any onChange event handlers have been called.

registerComponent(Counter, {
  name: 'Counter',
  prop: {
    onCountChange: {
      type: 'eventHandler',
      argTypes: [{ name: 'count', type: 'number' }]
    }
  },
  states: {
    count: {
      type: 'readonly',
      onChangeProp: 'onCountChange',
      variableType: 'number',
      initVal: 0
    }
  }
});

Note that for writable states, the initial value is specified as the defaultValue you registered for your valueProp.

You can also specify an initFunc instead, to derive the initial value from the component props:

PLASMIC.registerComponent(Counter, {
  name: "Counter",
  prop: {
    initCount: "number",
    onCountChange: ...
  },
  states: {
    count: {
      type: "readonly",
      onChangeProp: "onCountChange",
      variableType: "number",
      // Counter starts with $props.initCount
      initFunc: $props => $props.initCount
    }
  }
});

Transforming onChange args to state value

Often, the code component doesn’t call the onChange handler with the actual state value you intend to register; instead, you need to apply a transformation to obtain the state value from the handler arguments. For example, suppose your onChange prop for TextInput is called with a ChangeEvent instead of the new value of the input text:

PLASMIC.registerComponent(TextInput, {
  name: 'TextInput',
  props: {
    value: 'string',
    onChange: {
      type: 'eventHandler',
      argTypes: [{ name: 'event', type: 'object' }]
    }
  },
  states: {
    value: {
      type: 'writable',
      valueProp: 'value',
      variableType: 'text',
      onChangeProp: 'onChange',
      // Transform the argument to `onChange` to the state value
      onChangeArgsToValue: (event) => event.target.value
    }
  }
});

Component helper functions

Sometimes you need to specify functions that are used at run time to help your components work. You will need to put your functions somewhere that the generated code can find them. We call these “component helpers”. So far, the two examples of component helpers are initFunc and onChangeArgsToValue for working with component states.

The helpers you expose should be exported from some module at some path. For example,

export const TextInputHelpers = {
  states: {
    count: {
      initFunc: ($props) => $props.initValue,
      onChangeArgsToValue: (event) => event.target.value
    }
  }
};

When you register the component, you will also need to specify where to import the helper functions from, as well as pass in an imported instance!

import { TextInputHelpers } from "~/components/text-input";
registerComponent(TextInput, {
  ...
  componentHelpers: {
    // imported instance, containing the helper functions
    helpers: TextInputHelpers,

    // import path
    importPath: "~/components/text-input",
    importName: "TextInputHelpers"
  }
});

The imported instance you pass in as helpers is necessary for Plasmic Studio to find and use those helper functions, while the importPath is necessary for generated code to find those same helper functions.

Element types

The defaultValue of a slot allows you to pass in an element tree, like this:

registerComponent({
  name: 'Button',
  props: {
    children: {
      type: 'slot',
      defaultValue: [
        {
          type: 'text',
          value: 'Click me!'
        }
      ]
    }
  }
});

An “element” is a JSON object that defines either an HTML tag or a component instance.

Common element fields

Some fields are common to all types of elements:

Type-specific fields

Text elements

Renders an HTML tag with some text.

You can actually just use a plain string instead of a JSON object as an element, to specify an unstyled span of text.

Container elements

Renders an HTML tag that contains other elements.

Image elements

Renders an image tag

Input elements

Renders an input tag

Component instances

Renders an instance of some component

Default component instances

Your slot defaultValues can contain not only basic elements (like text/boxes/images) and instances of other code components, but also instances of the Plasmic “built-in” components like Buttons and Selects.

You can include these using code like the following:

{

  type: "default-component",
  kind: "button",
  props: { href: "#" }
}

Note that a Plasmic project might not have any Button component, in which case, one will be created. Or it can have multiple, in which case the default one is used (projects let you designate a component as the default component for Button). You can specify the default component by right-clicking it in the components list, clicking on “Set as default component” in the sub-menu, and selecting the kind for this component.

Template types

A “template” object defines a set of defaults to instantiate a component with. It accepts these fields:

Specifying templates is a great way to make your components easier to use by Studio users, especially if your component can be configured in many different ways. Studio users will be able to choose from this set of pre-defined templates when they insert this component.

Styles

defaultStyles and element.styles above take a CSSProperties object. However, for now, Plasmic’s accepted CSS has some specific requirements:

• Use individual atomic properties, such as fontFamily: 'Arial', fontSize: '18px', rather than shorthands like font: '18px Arial'.
• columnGap and rowGap are the properties to use to set gaps in horizontal/vertical boxes (we emulate flex gaps in the modern CSS standard).
• Some properties like fontFamily accept only a single value (no font fallbacks).
• When in doubt, try just opening up Plasmic Studio, which will sanitize/validate the style objects and inform you if there are issues.

Have feedback on this page? Let us know on our forum.