About Custom Element Installation with the CLI

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

How automatic installation works

Set installation.staticContainer to "HOMEPAGE" to automatically add the widget to the site's home page when the Wix user installs the app. Wix users can later move, resize, or remove it. If the field is omitted, the CLI doesn't add the widget to any page on install. It only appears in the editor's Add panel where Wix users must add it manually.

Installation configuration examples

Example 1: auto-add to home page

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

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 staticContainer: "HOMEPAGE" for the home page.
• Other widgets with the field omitted for header, footer, or specific pages, with instructions on where to add them.

You define configuration per widget in each custom element's extension file. For the full list of options, see Custom Element Extension Files and Code.

What you can and can't control

You can:

• Auto-add the widget to the home page on install with staticContainer: "HOMEPAGE".
• Skip automatic installation by omitting the field, 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 staticContainer 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.

Best practices for widget distribution

• Set clear expectations in your app description, dashboard, or first-run experience. State that the widget appears on the home page when staticContainer is set to "HOMEPAGE", 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 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 staticContainer: "HOMEPAGE" and 1 with the field omitted, and document which widget to add where.

See also

• Add a Custom Element Extension with the CLI
• Custom Element Extension Files and Code