Custom actions for code components

You can create components with custom action controls.

Custom actions are a type of control that is shown in the right sidebar, alongside your prop controls. Actions aren’t necessarily associated with any single prop, but they can read and update props.

When registering your component, specify your actions in the actions field.

Example

Copy
PLASMIC.registerComponent(CodeComponent, {
name: 'CodeComponent',
props: {
children: 'slot'
},
actions: [
{
// Creates a button that, on click, will append a new
// image element to the `children` slot of this
// component instance.
type: 'button-action',
label: 'Append new element',
onClick: ({ studioOps }) => {
studioOps.appendToSlot(
{
type: 'img',
src: '',
styles: {
maxWidth: '100%'
}
},
'children'
);
}
},
{
type: 'custom-action',
control: ({ studioOps }) => (
// A form that adds a new tab with the given key
const [value, setValue] = React.useState();
return (
<div>
<input
type="text"
value={value}
onChange={e => setValue(e.target.value)}
placeholder="Tab Key"
/>
<button onClick={() => {
studioOps.appendToSlot(
{
type: "component",
name: "TabPanel",
props: {
tabKey: value
}
},
"children"
);
}}>Create new tab</button>
</div>
)
)
}
]
});

You can find more examples here:

Action types

When creating a custom action, you can choose between one of these available types:

TypeDescription
button-actionCreates a single button. The user can click on the button to perform an action.
custom-actionCreates an arbitrary control that can render any React component you supply.

Common option

The only common option you need to specify is the type itself.

FieldRequired?description
typeYesOne of the supported action types

Type-specific options

Some additional options are only relevant to specific types:

button-action

FieldRequired?description
labelYesA string that will be the button label.
onClickYesA function that will be passed as the onClick handler of the button. The function will be called with an action props object as its argument.

custom-action

FieldRequired?description
controlYesThe custom React component that will be rendered on the right panel of Studio. The component will be instantiated with a action props object as its argument.

Action props

The action handlers and custom React component will all take in an “action props” object as argument, which contains these fields:

  • componentProps: The props that are currently configured for this component instance.
  • contextData: The data from setControlContextData() called from within your code component. See prop control functions.
  • studioOps: The provided set of operations that we can perform in the Plasmic studio.

Studio operations

The studioOps object exposes various operations that your custom action can perform in the Plasmic studio. These are:

showModal()

Show a Fullscreen modal with the content passed to children. It takes an onClose callback, which is fired if the users click outside.

Copy
showModal({
children: <div>This is my modal!</div>,
onClose: () => alert('Thank you for using this modal.')
});

refreshQueryData()

Refresh the fetched data from @plasmicapp/query for all the artboards in the editor. Useful if your custom action just updated the source data currently being rendered.

Copy
refreshQueryData();

appendToSlot()

Append a new element to a given slot of the component. The element to append should be in the Plasmic element type json format.

Copy
appendToSlot(element: PlasmicElement, slotName: string);

removeFromSlotAt()

Remove the element of a given position from a slot.

Copy
removeFromSlotAt(pos: number, slotName: string);

updateProps()

Update a set of non-slot props of the component. The set of props should be in JSON object format.

Copy
updateProps(newValues: any);

Give feedback on this page