> 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: Configure Custom Element Behavior

## Article: Configure Widget Behavior

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

## Article Content:

# Configure Widget Behavior

When you create a site widget with the Wix CLI, you can control how site builders interact with it in the editor. These settings are defined in your widget's `element.extension.ts` file and determine things like default dimensions, whether the widget is added automatically on install, and whether it's essential to your app.

## Available behavior settings

You can configure the following settings in your widget's `element.extension.ts` file. Available settings include the widget's dimensions, installation behavior, and dashboard page association.

### Dimensions

Control the widget's initial size and whether site builders can stretch it to full width:

```ts
export default extensions.customElement({
  // ...
  width: {
    defaultWidth: 450,
    allowStretch: true,
    stretchByDefault: false,
  },
  height: {
    defaultHeight: 250,
  },
});
```

| Setting | Description |
|---|---|
| `width.defaultWidth` | The widget's width in pixels when first installed on a site. |
| `width.allowStretch` | Whether to allow site builders to toggle the widget between full-width and default width. |
| `width.stretchByDefault` | Whether to stretch the widget to full width on installation. |
| `height.defaultHeight` | The widget's height in pixels when first installed on a site. |

### Installation behavior

Control how the widget is added to a site when your app is installed:

```ts
export default extensions.customElement({
  // ...
  installation: {
    autoAdd: true,
    essential: false,
  },
});
```

| Setting | Description |
|---|---|
| `installation.autoAdd` | If `true`, the widget is automatically added to the site's home page when the app is installed. If `false`, the site builder adds it manually from the Add Elements panel. |
| `installation.essential` | If `true`, the widget is a core part of your app. Deleting the widget (or the section or page containing it) also deletes the app. Can only be set to `true` if the widget is part of a [site page extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-pages/about-site-page-extensions.md). |

For more details and best practices, see [About Site Widget Installation with the Wix CLI](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/site-widgets/about-site-widget-installation-with-the-wix-cli.md).

### Dashboard page association

Associate a widget with one of your app's dashboard pages. When configured, a **Manage** button appears in the widget's action bar in the editor, allowing site builders to navigate directly to the linked dashboard page.

```ts
export default extensions.customElement({
  // ...
  behaviors: {
    dashboard: {
      dashboardPageComponentId: '154f642e-a705-4ff3-8421-6119354a3384',
    },
  },
});
```

Set `dashboardPageComponentId` to the `id` of the dashboard page extension you want to associate with the widget.

## See also

- [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)
- [About Site Widget Installation with the Wix CLI](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/site-widgets/about-site-widget-installation-with-the-wix-cli.md)
- [About Site Widget Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-widgets/about-site-widget-extensions.md)