Source code
Revision control
Copy as Markdown
Other Tools
# MozWidget
`moz-widget` is a card that embeds a self-contained, interactive widget in a host surface. Widgets are used for presenting brief updates or completing a quick task.
It clips content to its bounds and uses the dimensions set by the `size` attribute. Content comes from a browser or iframe when `src` is set and otherwise from the default slot.
```html story
<moz-widget widget-id="weather" size="medium">
<section style={{ padding: "16px" }}>
<h3>Los Angeles</h3>
<p>72°F and sunny</p>
</section>
</moz-widget>
```
## Code
The source for `moz-widget` can be found under [browser/components/widgets/content/](https://searchfox.org/firefox-main/source/browser/components/widgets/content).
## How to use `moz-widget`
### Importing the element
`moz-widget` is not registered by `customElements.js` and needs to be imported to use:
```html
<script
type="module"
src="chrome://browser/content/widgets/moz-widget.mjs"
></script>
```
### Setting the `size`
`size` selects fixed dimensions based on the IAB Medium Rectangle (300x250) but the host surface can override them.
A missing or unrecognized `size` uses the `large` dimensions.
The widget sets `--widget-size` to `small`, `medium`, or `large` for its header and content to query with `@container style()`.
<table>
<thead>
<tr>
<th><code>size</code></th>
<th>Width</th>
<th>Height</th>
<th>Ratio</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>large</code></td>
<td>300px</td>
<td>250px</td>
<td>6:5</td>
</tr>
<tr>
<td><code>medium</code></td>
<td>300px</td>
<td>125px</td>
<td>12:5</td>
</tr>
<tr>
<td><code>small</code></td>
<td>150px</td>
<td>125px</td>
<td>6:5</td>
</tr>
</tbody>
</table>
If a surface overrides the sizing, it should keep the dimensions close to the IAB rectangle as New Tab does.
### Setting the `widget-id`
`widget-id` is the registered ID of the hosted widget.
### Setting the `title`
`title` provides the accessible name of the widget.
Set `data-l10n-id` to a Fluent message with a `.title` attribute:
```
widget-weather =
.title = Weather
```
```html
<moz-widget widget-id="weather" data-l10n-id="widget-weather"></moz-widget>
```
Or set the attribute directly:
```html
<moz-widget widget-id="weather" title="Weather"></moz-widget>
```
### Adding a header
A `moz-widget-header` in the `header` slot appears above the widget content. `moz-widget` imports `moz-widget-header`.
`title` sets the header text:
```html
<moz-widget widget-id="weather" title="Weather">
<moz-widget-header slot="header" title="LA Weather"></moz-widget-header>
</moz-widget>
```
The `leading` slot holds content before the heading, such as a back button or a badge.
The `trailing` slot holds content at the end of the header.
In a `small` widget, the header hides a `moz-badge` in the `leading` slot, and hides the `trailing` slot when the header shows a menu button.
```html
<moz-widget widget-id="weather" title="Weather">
<moz-widget-header slot="header" title="Weather">
<moz-button
slot="leading"
type="ghost"
size="small"
iconsrc="chrome://global/skin/icons/arrow-left.svg"
data-l10n-id="weather-back-button"
></moz-button>
<moz-badge slot="leading" type="new" data-l10n-id="weather-new-badge"></moz-badge>
<moz-button
slot="trailing"
size="small"
iconsrc="chrome://global/skin/icons/arrow-down-12.svg"
iconposition="end"
data-l10n-id="weather-units-button"
></moz-button>
</moz-widget-header>
</moz-widget>
```
When `moz-widget`'s `menu` slot holds a `panel-list`, the header shows a menu button that opens it. A `panel-list` without an `id` gets a generated one. An `id` set by the surface has to be unique to its document or shadow root. `menu-label` sets the button's accessible name, which defaults to "More options":
```html
<moz-widget widget-id="weather" title="Weather">
<moz-widget-header slot="header" data-l10n-id="weather-header"></moz-widget-header>
<panel-list slot="menu" id="weather-menu">
<panel-item data-l10n-id="weather-refresh"></panel-item>
<hr />
<panel-item data-l10n-id="weather-remove"></panel-item>
</panel-list>
</moz-widget>
```
```ftl
weather-header =
.title = Weather
.menu-label = Weather options
```
### Setting `padded`
`padded` insets the card and rounds the corners of the content.
```html
<moz-widget widget-id="weather" title="Weather" padded>
<moz-widget-header slot="header" title="Weather"></moz-widget-header>
</moz-widget>
```
### Without a header
Without a header, the content extends to the card's edges. `moz-widget` draws the menu button over the top-end corner of the content, shown while the widget is hovered or focused, or while its menu is open. `menu-label` on `moz-widget` sets the button's accessible name.
```html
<moz-widget widget-id="weather" title="Weather" menu-label="Weather options">
<panel-list slot="menu">
<panel-item data-l10n-id="weather-refresh"></panel-item>
</panel-list>
</moz-widget>
```
### Remote content with `src`
`src` uses a remote frame for the widget content instead of the slotted content.
```html
<moz-widget
widget-id="weather"
title="Weather"
remote-type="extension"
group-id="GROUP_ID"
></moz-widget>
```
The frame is a `browser` element in chrome or an `iframe` element in content.
In a browser element, `remote-type="extension"` loads a `moz-extension:` document in the extension process, and `group-id` joins the extension's browsing context group, taken from `WebExtensionPolicy.browsingContextGroupId`.