About Site Widget Installation with the Wix CLI

In This Article

CLI Documentation Notice

You're viewing documentation for the new CLI, which we recommend for all new projects. Determine which CLI your project uses.

Previous CLI documentation:

CLI for Apps: See Site Widget Extension Files and Code for installation behavior.

When a Wix user installs your app, you can choose whether the CLI adds your custom element site widget to their site automatically. You set installation.autoAdd in your widget's extension file (element.extension.ts). This article explains how installation works, what you can configure, and how to get your widget on the pages you want.

How automatic installation works

Value	Behavior
`true`	The CLI automatically adds the widget to the site's home page when the Wix user installs the app. Wix users can later move, resize, or remove it.
`false`	The CLI doesn't add the widget to any page on install. It only appears in the editor's Add panel. The Wix user must add it manually to the pages they want.

Installation configuration examples

Example 1: auto-add to home page

Copy

Use this for a main landing experience widget. Wix users can move it to another page or section if they want.

Example 2: manual add only

Copy

Use this for header/footer widgets or when you want the Wix user to choose where to place the widget. You can document in your app or panel that they should add it to the header or footer and use the editor's Show on All Pages option so it appears site-wide.

Example 3: multiple widgets with different strategies

You can ship several widgets and set installation per widget:

1 widget with autoAdd: true for the home page.
Other widgets with autoAdd: false for header, footer, or specific pages, with instructions on where to add them.

You define configuration per widget in each widget's extension file. For the full list of options, including installation.essential, see Custom Element Site Widget Extension Files and Code.

What you can and can't control

You can:

Auto-add the widget to the home page on install with autoAdd: true.
Skip automatic installation with autoAdd: false, so the widget only appears in the editor's Add panel.
Ship multiple widgets, each with its own installation setting.

You can't:

Auto-add to master pages (header/footer), all pages, or specific page types.
Control widget placement with APIs. Placement is determined only by the autoAdd setting and by what the Wix user does in the editor.

For site-wide display, Wix users need to move the widget to the header or footer in the editor and enable Show on All Pages.

Set clear expectations in your app description, dashboard, or first-run experience. State that the widget appears on the home page when autoAdd is true, and that Wix users can move it.
Guide Wix users when site-wide display matters. If the widget should appear across the site (for example, a chat or banner widget), use your settings panel or dashboard to explain how to add it to the header/footer and enable Show on All Pages.
Add in-app guidance. Consider adding a setup checklist or tooltip directly in the widget's settings panel so Wix users don't have to leave your app to find placement information.
Design the widget for different placements. Use flexible width/height and responsive layout so the same widget works on the home page, in the header, or in the footer. See the width and height options in Custom Element Site Widget Extension Files and Code.
Consider multiple widgets. If you need 1 hero widget on the home page and another bar widget in the header, define 2 widgets: 1 with autoAdd: true and 1 with autoAdd: false, and document which widget to add where.

About Site Widget Installation with the CLI