> For the complete documentation index, see [llms.txt](https://docs.xibosignage.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xibosignage.com/developer/integrate/adding-widgets.md).

# Adding Widgets

A widget is added to a Layout or Playlist in a multi-step process.

{% stepper %}
{% step %}

### Locate module / template and playlist

Find the Module and optional Template you want to add, along with the playlist you want to add it to.
{% endstep %}

{% step %}

### Call “Add Widget”

Use the widget POST API to add the widget. The add widget API requires a `playlistId`; when working with a standalone playlist this is simply the ID obtained from playlist add or playlist search. However, when working with a layout you either need to add a region for your new widget to sit in, or add it to an existing region.

Once you have a `playlistId` for the region you’re adding against, you can use the widget POST API to add the widget. There are two key parameters to this API, aside from `playlistId`:

* `type`: The module type of the widget you’re trying to add. Use the Module Search API to find the one you want.
* `templateId`: If the module has a `dataType`, provide the ID of a module template returned by the Module Template Search API.

The `templateId` of `elements` is reserved for Elements, but is not available via the API yet.

Note: widgets and data widgets with static templates can be added via the API. It is not possible to add Elements via the API.
{% endstep %}

{% step %}

### Discover supported properties

Discover the properties supported by the module and the template. Any omitted properties will be set as their defaults.
{% endstep %}

{% step %}

### Call “Edit Widget” and supply properties

Call the Edit Widget API and supply the properties you discovered. When a widget is edited it is necessary to provide all properties for that widget’s module and its module template if it has one. Any omitted properties will be set as their defaults.
{% endstep %}
{% endstepper %}

**Types of region**

There are 4 types of region available:

* `zone`: Used only in templates and automatically converted to either a frame or playlist when a widget is added to them.
* `frame`: For single widgets (only one widget can be added).
* `playlist`: For multiple widgets which will play in sequence.
* `canvas`: For elements and not yet available via the API.

If you have a `frame` region and you use its `playlistId` to add another widget it will automatically be converted to a `playlist` with both widgets in sequence.

Hint: Regions are not applicable when adding a widget to a standalone playlist.

**Older versions**

Xibo CMS v3.3 and earlier had a more rigid set of API calls for adding widgets and did not cater for custom modules. They were still added in the same process, but the properties supported by the module were already documented in Swagger.

You can view each of these requests in the Swagger docs for those older versions.

Links:

* Adding Widgets: <https://account.xibosignage.com/docs/developer/cms-api/adding-widgets#content-adding-widgets>
* Types of region: <https://account.xibosignage.com/docs/developer/cms-api/adding-widgets#content-types-of-region>
* Editing Widgets: <https://account.xibosignage.com/docs/developer/cms-api/adding-widgets#content-editing-widgets>
* Older versions: <https://account.xibosignage.com/docs/developer/cms-api/adding-widgets#content-older-versions>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xibosignage.com/developer/integrate/adding-widgets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.