CUSTOM ELEMENT WIDGET · Wix App · wix/skills · Skills Docs

CUSTOM ELEMENT WIDGET · Wix App · wix/skills · Skills Docs

File	Purpose
`<name>.tsx`	The widget — a class that extends `HTMLElement`
`<name>.panel.tsx`	The settings panel React component shown in the Editor sidebar
`<name>.module.css`	CSS Modules stylesheet pre-wired with a `.root` class and CSS custom-property tokens
`<name>.extension.ts`	Builder file (UUID, name, sizing defaults, auto-add, presets, tagName, file paths)

import styles from './<name>.module.css';

class MyWidget extends HTMLElement {
  static get observedAttributes() { return ['display-name']; }

  constructor() { super(); }

  connectedCallback() { this.render(); }
  disconnectedCallback() { /* tear down timers, listeners */ }
  attributeChangedCallback() { this.render(); }

  render() {
    const displayName = this.getAttribute('display-name') || "Your Widget's Title";
    this.innerHTML = `<div class="${styles.root}"><h2>${displayName}</h2></div>`;
  }
}

export default MyWidget;

import React, { type FC } from 'react';
import ReactDOM from 'react-dom';
import reactToWebComponent from 'react-to-webcomponent';
import styles from './<name>.module.css';

const MyWidget: FC<{ displayName?: string }> = ({
  displayName = "Your Widget's Title",
}) => (
  <div className={styles.root}>
    <h2>{displayName}</h2>
  </div>
);

export default reactToWebComponent(MyWidget, React, ReactDOM as any, {
  props: { displayName: 'string' },
});

Field	Type	Default	Purpose
`id`	UUID	generated	Extension ID. Don’t change after scaffolding.
`name`	string	from scaffold param	Display name. Maximum 30 characters — longer names cause a platform validation error on deployment.
`tagName`	kebab-case	derived from `folder`	Custom-element tag the widget is registered under. Used by the Editor and by `customElements.define()`.
`width.defaultWidth`	number (px)	`450`	Initial width when the widget is added to a page.
`width.allowStretch`	boolean	`true`	Whether the site owner can stretch the widget to the page width.
`height.defaultHeight`	number (px)	`250`	Initial height.
`installation.autoAdd`	boolean	`true`	If true, the widget is auto-added to the site when the app is installed. Set to `false` for opt-in widgets.
`presets`	array	one default preset	Editor presets (saved configurations) the site owner can pick from. Each preset has its own `id`, `name`, and `thumbnailUrl`.
`presets[].thumbnailUrl`	string	`{{BASE_URL}}/<name>-thumbnail.png`	Path to a preview image. `{{BASE_URL}}` is resolved at build time. Replace the placeholder image at the same relative path with your actual asset.
`element`	path	`./extensions/site/widgets/<name>/<name>.tsx`	Path to the widget custom element file. Don’t change unless renaming files.
`settings`	path	`./extensions/site/widgets/<name>/<name>.panel.tsx`	Path to the settings panel file. Don’t change unless renaming files.

Side	Convention	Example
`<name>.tsx` — `observedAttributes`, `getAttribute`	kebab-case	`"display-name"`, `"bg-color"`
`<name>.panel.tsx` — `widget.getProp` / `widget.setProp`	kebab-case	`"display-name"`, `"bg-color"`
Local TypeScript variables	camelCase	`displayName`, `bgColor`

Side	Convention	Example
`reactToWebComponent` `props` option	camelCase	`{ displayName: 'string' }`
React component props interface	camelCase	`displayName?: string`
`<name>.panel.tsx` — `widget.getProp` / `widget.setProp`	kebab-case	`"display-name"`, `"bg-color"`

import { items } from '@wix/data';
import { window as wixWindow } from '@wix/site-window';

class MyWidget extends HTMLElement {
  static get observedAttributes() {
    return ['collection-id'];
  }

  constructor() {
    super();
  }

  connectedCallback() {
    this.render();
  }

  attributeChangedCallback() {
    this.render();
  }

  async render() {
    const collectionId = this.getAttribute('collection-id') || '';
    const viewMode = await wixWindow.viewMode();

    if (viewMode === 'Editor') {
      this.innerHTML = `
        <div style="padding: 20px; border: 2px dashed #ccc">
          <p>Widget will display data on the live site</p>
          <p>Collection: ${collectionId}</p>
        </div>
      `;
      return;
    }

    try {
      const { items: results } = await items.query(collectionId).limit(10).find();
      this.innerHTML = results.map((item) => `<div>${item.title}</div>`).join('');
    } catch (error) {
      console.error('Failed to load data:', error);
    }
  }
}

export default MyWidget;

const [results, setResults] = useState<string[]>([]);
const [isEditor, setIsEditor] = useState(false);

useEffect(() => {
  wixWindow.viewMode().then((viewMode) => {
    if (viewMode === 'Editor') { setIsEditor(true); return; }
    items.query(collectionId).limit(10).find()
      .then(({ items: data }) => setResults(data.map((item) => item.title as string)))
      .catch((err) => console.error('Failed to load data:', err));
  });
}, [collectionId]);

// render: if (isEditor) return <placeholder />; else return <results />;

Picker	API	Preview component	Value type
Color	`inputs.selectColor(value, { onChange })` from `@wix/editor`	`<FillPreview fill={value} onClick={...} />`	`string`
Font	`inputs.selectFont(value, { onChange })` from `@wix/editor`	`<Button onClick={...}>Change Font</Button>`	`{ font: string; textDecoration: string }` — store as `JSON.stringify()`

// Color — inside a SidePanel.Field > FormField
<FillPreview
  fill={bgColor}
  onClick={() => inputs.selectColor(bgColor, {
    onChange: (val) => { if (val) { setBgColor(val); widget.setProp('bg-color', val); } }
  })}
/>

// Font — inside a SidePanel.Field > FormField
<Button onClick={() => inputs.selectFont(font, {
  onChange: (val) => {
    const next = { font: val.font, textDecoration: val.textDecoration || '' };
    setFont(next);
    widget.setProp('font', JSON.stringify(next));
  }
})}>Change Font</Button>