How to build a custom React component (ERC) in Studio Two

4 days ago

4 min read

Updated: 6 hours ago

Build an Editor React Component (ERC) component first. Scaffold it from the Code tab with the Wix Extension Builder, write the React code, props and CSS, then regenerate the editorElement part of the manifest. Refine the manifest you own, check the result on the Design canvas, and publish.

Before you start

A Studio Two site project with the Code tab and the Wix Extension Builder available.
Working knowledge of React, TypeScript and CSS Modules.
A plan for which props and CSS properties Wix users should be able to edit.
Publicly reachable URLs for preset thumbnails and preset CSS, if you add presets.

Step by step

Scaffold the component. In the Code tab, open the Wix Extension Builder and choose Site > Editor React Component. On a welcome screen, pick the custom component option instead. Enter a Name (up to 30 characters) and a required Component description, then click Generate.
Find the generated files. The files appear under src/extensions/site/components/<component-folder>/ and the extension is registered in extensions.ts. You mainly edit the .tsx, .props.ts, .module.css and .extension.ts files. Leave component.tsx as generated. Save with Control+S or Command+S and wait for the status bar to show Synced.
Write the component markup. Put your JSX in <component-folder>.tsx. The root element needs the id and className props Wix passes in, plus a plain string class that the manifest selector matches. Every element the editor should target also needs a plain string class next to its CSS Module class, because module class names are rewritten at build time.
Declare props and defaults. In <component-folder>.props.ts, define the props type and a defaultProps constant. Each prop becomes editable content, and the default feeds both the rendered component and the editor panels. Leave id and className out of defaultProps.
Update the preview file. If you renamed or replaced props, edit component.preview.tsx. List your own content props in requiredDataFields, not id or className. A listed field that the component no longer has makes the canvas show a placeholder.
Style with CSS Modules. Write default styles in <component-folder>.module.css. The CSS properties you set here become the design controls Wix users get. A property you never style is not offered.
Regenerate the manifest. Open the terminal in the Code tab (Control+J or Command+J) and run the manifest regeneration command from the guide. Then read <component-folder>.generated.ts: props appear under data, classed elements under elements, and styled properties under cssProperties. Do not edit this file, because regeneration overwrites it.
Refine the manifest you own. Make overrides in <component-folder>.extension.ts, which regeneration never overwrites. The scaffold merges your values onto the generated editorElement with deepmerge. Typical changes are displayName labels, selectable inner elements, displayGroups, displayFilters, layout and installation.initialSize.
Add presets. Wrap the root element in a container, spread wix.presetsWrapperProps onto it, and keep id and className on the inner element. Declare presets in the deepmerge object, set installation.presets, and give each preset a thumbnailUrl and presetCssUrl. Use presetDefaults for values applied on switching, and styleOverrides for values that vary by breakpoint or state.
Add states. Declare states in the same deepmerge object. Use pseudoClass with a NATIVE_STATE_TYPE value for browser states such as hover, className for custom states such as loading, and props to show the state on the canvas. In the CSS module, target both the pseudo-class and the state class wrapped in :global(). Optionally set statesDefaultValues on a property.
Check the component in the editor. On the Design tab, go to Add Elements > AI Generated and place a fresh copy of the component. Confirm the defaults show, Edit Text lists each text prop, and selectable inner elements have their own action bars. Use Preview to see the page outside edit mode.
Publish the site. Click Publish in the Studio Two editor. The ERC ships with the published site.

Good to know

A changed default applies only to copies added after you save. A copy already on a page keeps its original values, so add a fresh copy after each round of changes.
Without both the id and a matching plain string class on the root, the component renders but Wix users cannot select it or open its panels.
Some type properties are immutable after the manifest is first saved, including dataType on a data item and elementType on an element. Changing them fails validation and blocks deployment. Add a new variable instead.
Every key referenced in presetDefaults or styleOverrides must exist in editorElement. Otherwise Site code errors reports that referenced keys do not exist and the component stops loading on the canvas. For example, background-color appears as background.
Generated elements have inlineElement.behaviors.selectable set to false until you change it in the manifest you own.
Besides writing a component in the Code tab, you can upload or paste a React component file, or describe an element in text or with an image and let Aria generate it.

parnii note

Work on a copy of the site first. Schema type changes can block deployment once the manifest has been saved. Check key names in the generated file before you reference them in presets.

FAQ

Why does my ERC show a placeholder on the canvas?

The requiredDataFields list in component.preview.tsx probably names a prop the component no longer has. List your own content props there, then regenerate the manifest.

Why is a control missing from the ERC panels?

The prop was probably not declared, or the CSS property was never styled. Fix it in the source files and regenerate the manifest. A missing element usually has a module class but no plain string class.

Can I edit the generated.ts file in an ERC?

No. Regenerating the manifest overwrites <component-folder>.generated.ts. Put your changes in <component-folder>.extension.ts, which regeneration never overwrites.