When creating a self-hosted site widget, a self-hosted site plugin, a site widget built with the CLI, or a site plugin built with the CLI, 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, use the Widget API’s setProp() function. Widget properties are bound to your custom element’s attributes, so any change in the properties automatically updates the corresponding attribute. To handle attribute updates so they are reflected in your widget in the editor, use the attributeChangedCallback() in your custom element's code.
Here is a sample code snippet showing how to update a custom element’s attribute:
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.For security reasons, the app instance ID isn’t directly accessible in site widgets or settings panels. Instead, you can securely extract it by sending a Wix access token to a backend API. The backend can decode the token, retrieve the instance ID, and perform any necessary business logic.
For implementation details, see: