COMPONENT API

Rules

Component Props Structure

Propagate elementProps to inner elements

elementProps is a map keyed by the manifest’s inner-element keys; each entry carries that element’s className (the editor sets it — this is how design states reach the element) plus any data.

Every named inner element — every element that carries a global class string — gets an elementProps entry, and you spread that entry onto the element. This is mandatory, even when the element needs no other config: without it the editor cannot style that element or drive its states.

How className gets merged depends on what the element is:

• Raw HTML element (<button>, <li>, <div>): merge elementProps?.<key>.className inline, alongside the global string and module class — there’s no component to do it.
• Sub-component built with this skill (<Inner/>): the spread alone is enough. className rides along inside it, and the sub-component merges it onto its own root (every skill component merges its incoming className). Don’t merge it again at the call site.

Non-parts (module-class-only elements: icons, decorations, separators, layout wrappers — no global class) get no entry. Style them with CSS.

Inside each entry, add only the config the element needs (data, direction, event handlers). Never add a bare className? as the only field to decide whether an element qualifies — className always flows through; the entry exists because the element is a named part.

What Qualifies as a Part

See PARTS.md for root election (Step 0), the mandatory filter, and full rules. The root gets no elementProps entry — its className, a11y, and direction arrive as top-level props.

Derived values are not props

If a displayed value can be computed with a simple pure function from other props and/or internal state, compute it internally — don’t expose it as a prop. Expose only the source inputs (use numeric types when arithmetic is needed: price: number, not price: string).

Example: subtotal = price × quantity → computed inside the component, not a prop.

Data-Driven Components (NO children in exported props)

• Component’s exported interface must NOT accept children prop
• ALL content MUST come through explicit named props (see “Derived values” above for what stays internal):
  • Text (labels, placeholders, messages) → label, text, placeholder, etc.
  • Media (images, videos, icons) → imageSrc, videoUrl, iconName, etc.
  • Links (URLs, hrefs) → link, href, url, etc.
  • Collections (list items, options, menu items) → items, options, menuItems, etc.
• Internal implementation can use children for composition between sub-components
• Hardcoded values are ONLY for fallback defaults when props are undefined

Exception — Container-type components: Components whose purpose is to wrap arbitrary child elements (e.g., BoxContainer) MAY accept children: React.ReactNode. This applies only to structural containers — data-driven leaf components (Button, Tabs, Accordion, etc.) must NOT use children.

Array Props: Data on Parent Only

When the parent component defines an array prop (e.g., items), child/item components receive a single item directly. They do NOT redeclare the data structure in their own props.

Array Element Types: Always Objects with Named Keys

Array elements MUST be objects with named keys. This enables stable item identity (each item can carry its own id/key), non-breaking extension (new fields can be added later without changing the prop signature), and semantic naming (each value has meaning instead of being an opaque scalar).

Allowed forms:

• Inline object literal: Array<{ key: ValueType, ... }>
• Named interface where the interface itself is an object with named keys (e.g. Array<AccordionItem> is OK because AccordionItem is { name, content })

Never allowed as the array element:

• Primitives: Array<string>, Array<number>, Array<boolean>
• Leaf data types from @wix/editor-react-types: Array<Image>, Array<Link>, Array<Video>, Array<Audio>, Array<VectorArt>, Array<RichText>. Wrap them in an object instead.
• Nested arrays: Array<Array<{cover: image, caption: string}>> Array<{items: Array<image>, caption: string}>

❌ Wrong:

✅ Correct:

Container Components (Blackbox Content)

When a component specification indicates a “container” or “slot” area where users can add nested content, use React.ReactNode for that content prop.

When to use React.ReactNode for a content prop:

• The specification describes a “container” or “content area”
• Users should be able to add arbitrary nested components
• The component doesn’t control what goes inside that area

RTL Support: Elements that render React.ReactNode content MUST have dir="ltr" to prevent RTL inheritance from the parent component. See DIRECTIONALITY.md.

Component Data Types

When creating TypeScript interfaces for component props, use types from @wix/editor-react-types for more complex types, to see the allowed type from this library, look at the following file node_modules/@wix/react-component-schema/dist/editor-react-types.d.ts:

External resources are forbidden

All resources rendered or fetched by the component (images, icons, fonts, videos, audio, JSON data, etc.) MUST come from Wix services. Never reference or call external (non-Wix) hosts — no unsplash.com, placehold.co, picsum.photos, third-party CDN icon sets, or any custom backend the user hasn’t asked for. This rule covers both src/href attributes and any runtime fetching.

Allowed image hosts: static.wixstatic.com (and other *.wixstatic.com subdomains). Allowed data: values supplied through props (populated by the editor) or imported local assets bundled with the component.

Default values for Image props

Image defaults belong in the <componentName>.props.ts file’s exported defaultProps constant (consumed by withDefaults(Component, defaultProps) in component.tsx). Use a Wix-hosted image from the Free-from-Wix public media catalog and populate only uri, url, and alt — leave width, height, focalPoint, etc. unset so the editor fills them when the user picks a real image.

By default, use the canonical fallback URL from the examples below for every Image default (url and uri derived from the same fileName). Only when the user explicitly asks for different/better default images, fetch candidates from the Wix Free-from-Wix catalog:

The endpoint is unauthenticated. Pick an item whose displayTags / title fit the component’s purpose, then build the Image default from its fileName:

• url → `https://static.wixstatic.com/media/${fileName}`
• uri → fileName
• alt → a short human description (use the item’s title or displayTags)

Do not call this endpoint when the user hasn’t asked for it — the canonical fallback URL is fine for unattended scaffolds.

Default image pool — use a different image for each slot:

When a component needs more than one image default, cycle through the pool above so every slot gets a visually distinct image. For a single image, use image #1.

Single Image prop:

Array of objects with an Image field:

Inline fallback for HTML src / href: when rendering a raw HTML attribute that takes a URL (<img src>, <source src>, <video poster>, <a href> for an image link, etc.) and the value could be empty, fall back to the same Wix-hosted URL — never to an external host or a relative path that doesn’t exist:

Component File Splitting

Split logical UI pieces into separate named components. Never write inline JSX blocks for distinct complex UI pieces.

File structure for complex components (many subcomponents):

When to extract a sub-component:

• JSX block represents a logical complex unit (button, control, section, item)
• Component has its own props interface
• Logic is reusable or testable independently
• Block has more than 15-20 lines of JSX

Patterns

Data-Driven Pattern

❌ Wrong:

✅ Correct:

Component controls rendering internally:

Array Props Pattern

Parent defines array structure, child receives single item:

Container Components Pattern

For “container” or “slot” areas, use React.ReactNode:

Common Mistakes

Using children prop in exported interface

❌ Wrong:

✅ Correct:

Adding elementProps for CSS-only elements

❌ Wrong:

✅ Correct:

Why: Don’t declare a className?: field — className already flows through each named inner element’s elementProps entry (see “Propagate elementProps to inner elements”). Conditional display is controlled via CSS, not React props.

Using T[] array syntax

Use Array<T> over T[].

❌ Wrong:

✅ Correct:

See also: Array Element Types: Always Objects with Named Keys — items must be objects with named keys.