Code components API reference

Component registration

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

Copy
// For PlasmicComponent users:
PLASMIC.registerComponent(component: React.ComponentType<any>, meta: ComponentMeta): void;
// Or for codegen users:
function registerComponent(component: React.ComponentType<any>, meta: ComponentMeta): void;

The first parameter component is the component you want to register and use in the Studio.

The second parameter meta is an object containing metadata about the component:

  • meta.name: A unique string name used to identify that component. Each component should be registered with a different meta.name.

    We encourage setting a name that matches the component’s name in code.

  • meta.props: An object describing the component properties to be used in Studio. For each prop, there should be an entry meta.props[prop].

    • meta.props[key]: The type of the property identified by key. The types are specified in the form of PropType (see more information below).
  • meta.importPath: (Codegen only) The path to be used when importing that component in the generated code. It can be the name of the package that contains the component, or the path to the file in the project (relative to the root directory).

  • meta.displayName: The name to be displayed for the component in Studio. Optional: if not specified, meta.name is used.

  • meta.importName: (Codegen only) The javascript name to be used when generating code. Optional: if not provided, meta.name is used.

  • isDefaultExport: (Codegen only) Whether the component is the default export from that path. Optional: if not specified, it’s considered false.

  • classNameProp: The prop that expects the CSS classes with styles to be applied to the component. Optional: if not specified, Plasmic will expect it to be className.

  • refProp: The 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. Optional: If not provided, the usual ref is used.

  • defaultStyles: A CSSProperties object with styles to be applied whenever creating an instance of the component in the Studio. See below section on styles. (Optional)

  • templates: An object describing templates to start with when creating instances of the component. meta.templates[templateName] is expected to follow the ComponentTemplate schema (see the element types section). (Optional)

Notice that Plasmic uses className to style components, so if the component doesn’t accept CSS classes, it won’t be able to receive styles from the Studio.

Similarly, Plasmic uses React refs in the Studio by default, so function components are expected to be wrapped in React.forwardRef. However, it’s also possible to setup the host app to work with components that don’t expose refs - see the function code components topic.

The main difference between the Loader and Codegen versions of this function is that the Codegen version takes metadata about how to import the component, such that the emitted code can directly access it. With Loader, the developer must manage the imports (see later section on tree-shaking).

Property types

PropType is used to describe the types of the properties registered with the component. It can be:

  • "string", "boolean", "number" for those javascript primitive types.

  • "object" for arbitrary JSON values, including objects and arrays.

  • "slot" for props that expect React elements, which will be treated as Plasmic slots.

  • Or an object obj containing:

    • obj.type: Any of the above strings, specifying the types, or "choice" when the type is defined by a list of options.
    • obj.options: Only applicable to "choice" type. Expects a list of strings containing the options to be passed to the prop.
    • obj.defaultValue: The default value that should be provided to the prop. Optional: If not present, and no value is passed when the component is instantiated, Plasmic won’t provide any value. For slots, the default value is expected to follow the PlasmicElement schema (see the element types section) or an array of those.
    • obj.editOnly: A boolean indicating whether the values passed to that prop should be used in the generated code. If true, the values will be used only in the editor, and might optionally be mapped to another prop via obj.uncontrolledProp. Optional: if not specified, it’s assumed to be false. Not applicable to "slot" type.
    • obj.uncontrolledProp: Only applicable when obj.editOnly is true. Should contain a string containing the name of prop that should receive the values in the generated code. Optional: if not provided (and obj.editOnly is true), then the values set in the editor will not be provided to any prop in the generated code.
    • obj.allowedComponents: Only applicable to "slot" type. A list of strings containing the unique names (meta.name) of the components that might be passed into this slot. For example, if a Menu only expects children of type MenuItem, it would contain ["MenuItem"]. Optional: if not provided, any component or element can be provided to the slot in the editor.

Element types

This describes the schema of what you can pass in as the defaultValue of any prop of type slot, such as:

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

An element (PlasmicElement) can be described as an object with the following fields:

  • element.type: A string to identify the type of the element: "text" (for texts, including links), "vbox" (vertical box), "hbox" (horizontal box), "box" (free box), "button", "img" (external image), "input" (text input), "password" (passowrd input), "textarea" (multiline text input), or "component" (for instances of a code component).

  • element.styles: A CSSProperties object with styles to be applied to the element. See below section on styles. (Optional)

  • element.attrs: An object containing the HTML attributes to be set for the element. Not applicable for "component" elements. (Optional)

Some types of elements also include specific fields:

  • element.src: Only applicable to "img" elements. Expects a string containing the URL of the image.

  • element.tag: Only applicable to "text", "vbox", "hbox" and "box" elements. Expects a string containing the HTML tag to be used for the element. Optional: if not specified, defaults to "div".

  • element.value: Only applicable to "text" and "button" elements. Expects a string with the element text content.

  • element.children: Only applicable to "vbox", "hbox" and "box" elements. Expects a PlasmicElement (or an array of those) - the children elements of the container.

  • element.name: Only applicable to "component" elements. Expects the registered name (meta.name) for the code component to be instantiated.

  • element.props: Only applicable to "component" elements. Expects an object with the props to be provided to the component. Optional. element.props[propName] can be:

    • A javascript scalar value to be passed to that prop.
    • An object (or an array of objects) of type PlasmicElement, for slot props.
    • An object JsonElement for any other JSON values, such that JsonElement.type is "json" and JsonElement.value contains the JSON value to be provided to that prop.

PlasmicElement also accepts a string for unstyled text elements (equivalent to creating an unstyled "text" element).

We also offer a ComponentTemplate schema, which defines a template for a code component. It’s an object with the following fields:

  • template.styles: Same as PlasmicElement.styles. (Optional)
  • template.props: Same as PlasmicElement.props for "component" elements. (Optional)
  • template.previewImg: A string with the URL of an image preview for this template, to help identifying it. (Optional)

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.

Give feedback on this page