When creating a self-managed site widget, a self-managed site plugin, a site widget built with the CLI, or a site plugin built with the CLI for Apps, you also need to create a settings panel, enabling users to customize the widget or plugin in the editor.
The settings panel is displayed when users click the Settings button in the widget or plugin's action bar. It's rendered as an iframe, giving you the flexibility to build it using any tools or frameworks you choose.
Note: For site widgets created with Wix Blocks, you can build custom panels directly within the Blocks editor.
When designing your settings panel's UI, ensure it is intuitive and user-friendly. Consider using the Wix Design System to maintain a cohesive design.
Use components such as:
SidePanel to create a structured layout.FormField and input components to collect user input effectively.These tools help you design a panel that aligns with the overall Wix editor experience.
In the panel's code, use Wix's JavaScript SDK to access widget properties and retrieve environmental data from the editor, as well as access and manage Wix business solutions.
To apply changes made in the settings panel to the widget, call the setProp() method in the Widget API. Widget properties are bound to your custom element's attributes, so any change in the properties automatically updates the corresponding attribute. To reflect attribute updates in your widget in the editor, list each attribute your custom element responds to in observedAttributes, and handle updates in attributeChangedCallback(). The browser calls attributeChangedCallback() only for attributes listed in observedAttributes.
If you use the generated React code for a site widget built with the CLI or a site plugin built with the CLI for Apps, you don't need observedAttributes or attributeChangedCallback(), because reactToWebComponent() handles attribute updates for you. For details, see Custom Element Extension Files and Code for site widgets, or Site Plugin Extension Files and Code for CLI for Apps site plugins.
Here is a sample code snippet showing how to update a custom element's attribute:
When updating more than one widget property from the settings panel, write properties one at a time. Await each setProp() call, then confirm the value with getProp() before writing the next property. This avoids later writes overwriting earlier ones that are still pending.
Enhance the user experience by integrating Wix's native color and font pickers. These tools allow users to select from their site's theme colors and fonts, ensuring consistency with the site's design.
Learn more about using Wix's color and font pickers.
Wix sites expose theme styles as CSS variables, which include tokens for colors and fonts. These variables enable your widget to automatically adopt the site's theme, ensuring seamless visual integration.
Learn more about connecting colors and fonts to a site theme.
An app instance represents a specific installation of your app on a Wix site, identified by a unique instanceId.
You may need the instance ID for various purposes, such as:
instanceId as a foreign key to save data like user preferences or analytics.Last updated: 14 October 2026