About Editor React Component Extensions

Editor React Component extensions let you build custom site widgets in React that fully integrate with the editor. You describe your component's customizable parts in a declarative manifest, and the editor builds matching auto panels for Wix users.

This gives Wix users the same editing experience they get with built-in Wix elements, without you having to build or maintain your own settings panels like you would with a custom element. To see auto panels appear one by one as you add manifest properties, follow the step-by-step tutorial.

For a walkthrough of Editor React Components, watch the video tutorial:

How it works

Your extension has 2 main parts:

• React component: Your UI code that renders in the editor and on the live site.
• Manifest: A configuration object that declares what's customizable about your component, so the editor knows which auto panels and controls to show to Wix users.

You build the React component first. The CLI then auto-generates the large part of the manifest for you. For more information, see Auto-generated manifest.

Your component code may also include additional assets like stylesheets, and you can provide separate bundles for the live site and the editor. For more details, see resources.

When a Wix user adds your component to their site:

1. The editor reads the manifest to understand what customizations are available.
2. The editor builds the matching auto panels and controls in the editor UI.
3. As the Wix user makes changes, the editor stores those values. It passes data changes to your component as props and applies style changes as CSS directly to the DOM elements that match the selectors in the manifest. TypeScript types for all props are available from the @wix/editor-react-types package.

Example

Here's a testimonial card built as an Editor React Component. The component code comes first, then the manifest that drives it.

React component:

The component follows a few conventions that let the editor manage it: it applies id and className to the root element, gives that element a testimonial-card class for the manifest to target, and puts classes like .quote and .author-name on the inner elements it wants to expose. Your own components need to do the same. For the full list, see Component requirements.

Manifest:

The selector (.testimonial-card) matches the CSS class on the component's root element. Everything else in the manifest drives an auto panel.

Each data property with dataType: "text" becomes an editable text field. When a Wix user clicks Edit Text on the component, the editor builds an Edit Text auto panel with inputs for every text property. The displayName value appears as the label for each input:

Properties with dataType: "image" surface in the Settings auto panel, where Wix users can upload or choose images from the Wix Media Manager:

The cssProperties configure a full Design auto panel with controls for fill colors, borders, corners, shadows, and spacing. The editor maps each CSS property to the appropriate design control:

Component requirements

For the editor to style, select, and configure your component, it needs to follow these conventions:

• Export a default function component.
• Accept the id and className props and apply both to the root element. id is what makes your component selectable in the editor, and className is how the editor delivers styling. For details, see Runtime Props.
• Give the root element its own class, and set the manifest's selector to match it.
• Add classes to any inner elements you want the manifest to target.
• Name your data props to match the keys in the manifest's data definition.

Some manifest features may require additional component-side setup, such as a wrapper element for presets and prop handling for interaction states. The tutorial on configuring auto panels covers these as they come up.

Make your component selectable

Before a Wix user can click your component on the stage and open its panels, the editor has to be able to find it. That takes 2 things working together, and if either one is missing your component renders but can't be selected:

• The manifest's selector has to match a class on your root element. This tells the editor which element in your rendered output is the component.
• That same root element has to carry the id prop. This lets the editor find the individual instance of your component in the page's DOM.

Selector rules

The manifest's selector fields are DOM query selectors. The editor runs them against your component's rendered output, so they have to describe the DOM you actually produce. The same applies to the selector on each inner element.

• Match the class that actually renders. CSS Modules rewrite class names at build time: a .card rule in your .module.css file might reach the browser as class="_card_1a2b3". So if your JSX applies styles.card and your manifest says selector: '.card', the selector matches nothing. Give the element a plain string class for the manifest to target, alongside your CSS Modules class:

  Copy

  testimonial-card is written as a literal, so it reaches the DOM unchanged and selector: '.testimonial-card' finds it. styles.card carries your own styling, and className carries the editor's.

• Keep the root selector specific. Selectors must be 4 to 50 characters. Name your root class after your component, such as .testimonial-card, so it can't collide with another component on the page. Inner element classes can be shorter and simply name the part, such as .title or .image.

• Prefer classes over tags and attributes. The manifest accepts any valid DOM selector, but tag and attribute selectors match too broadly, and the editor nests CSS variable scoping by selector.

• Regenerate the manifest after you rename a class. The auto-generated editorElement holds the selector it read from your code at generation time. If you rename a class and don't run wix generate manifest, the manifest still points at the old class and stops matching anything.

Runtime props

As Wix users edit your component, the editor passes updated values to it as React props. Data values like text and numbers arrive as top-level props, while style changes are applied directly to the DOM as inline CSS.

Some data types, like images and vector art, use complex object formats at runtime. The @wix/editor-react-types package provides TypeScript types for these values.

For the full breakdown of prop categories, see Runtime Props.

What you can configure

The testimonial card example covers a simple case: editable text, an image, and some design properties. Most components go further. A slideshow has navigation arrows, a menu has items with hover states, a card grid needs layout controls. Through the manifest, you can also configure inner elements with their own auto panels, interaction states, layout and resize behavior, presets, animations, and richer data types.

For the full set of auto panels and the manifest properties that drive each one, see About Auto Panels. For the per-property manifest reference, see About the Manifest.

Get started

You can add an Editor React Component extension using the CLI. The CLI scaffolds your component files, auto-generates the editorElement portion of the manifest from your React code, handles bundling, and manages deployment.

From there, you can develop your component:

• With an AI agent: Use Wix skills from a supported AI coding agent to build and update components. The skills regenerate the manifest as it works.
• Manually: Edit the component source directly. After manual changes, run wix generate manifest to update the auto-generated manifest.

Limitations

The following limitations apply to Editor React Components. For manifest-specific rules and unsupported features, see About the Manifest.

• Custom panels aren't supported. Only auto panels are available. You can't ship your own React UI for an editor panel, so anything Wix users can configure has to map to a manifest property.
• Self-hosting: Self-hosting for Editor React Component extensions isn't supported. Deploy components using the CLI.

See also

• About Auto Panels
• About the Manifest
• Tutorial | Configure Auto Panels