> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: About Custom Element Installation with the Wix CLI

## Article: About Site Widget Installation with the Wix CLI

## Article Link: https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/custom-elements/installation-and-behavior/about-custom-element-installation-with-the-wix-cli.md

## Article Content:

# About Site Widget Installation with the CLI

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

```typescript
// element.extension.ts
import { extensions } from '@wix/astro/builders';

export default extensions.customElement({
  id: '...',
  name: 'Home Hero Widget',
  width: { defaultWidth: 1200, allowStretch: true },
  height: { defaultHeight: 400 },
  installation: {
    autoAdd: true,
  },
  // ...
});
```

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

```typescript
// element.extension.ts
import { extensions } from '@wix/astro/builders';

export default extensions.customElement({
  id: '...',
  name: 'Header Bar Widget',
  width: { defaultWidth: 1400, allowStretch: true },
  height: { defaultHeight: 60 },
  installation: {
    autoAdd: false,
  },
  // ...
});
```

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](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/custom-elements/custom-element-extension-files-and-code.md).

## 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**.

## 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 `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](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/custom-elements/custom-element-extension-files-and-code.md).
- 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.

## See also

- [Add a Custom Element Site Widget Extension with the CLI](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/custom-elements/add-a-custom-element-extension.md)
- [Custom Element Site Widget Extension Files and Code](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/custom-elements/custom-element-extension-files-and-code.md)