> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/main-dashboard/dashboard-widgets.md).
# Dashboard widgets
{% hint style="warning" %}
All dashboard widgets require a configured TMDb metadata key.
Without it, CW hides these widgets on the **Main** page. Set it up in [TMDb Metadata](/crosswatch/settings/connections/metadata/tmdb-metadata.md).
{% endhint %}
Media widgets on the Main page, including watchlist, history, ratings, and scrobble summaries.
{% tabs %}
{% tab title="End users" %}
### Available widgets
#### Watchlist
Shows recently synchronized watchlist items.
Select a media item to open its details. Select **View all** to open the complete [Watchlist](/crosswatch/main-dashboard/navigation/watchlist.md) page.
#### Recent History
Shows the latest watched movies, shows, seasons, and episodes found in provider state and the CrossWatch tracker.
Episode entries include the season and episode number when available.
#### Latest Ratings
Shows the latest ratings found in provider state and the CrossWatch tracker.
Each entry can include the rating value, media type, timestamp, and provider sources.
#### Recent Scrobble
Shows recent successful scrobble activity.
Entries can show the source media server, destination trackers, playback event, and the route used by CrossWatch.
#### Recent Progress
Shows recent resume position synchronization activity.
Entries include the synchronized progress percentage and the provider sources involved.
This widget only contains data when Progress is enabled on a supported media server pair.
#### Recent Playlists
Shows recent playlist synchronization activity.
Entries can include the mapping profile, action, status, and the number of added or removed items.
This widget only contains data after a playlist mapping has run.
### Opening media details
Select a media item in Watchlist, Recent History, Latest Ratings, Recent Scrobble, or Recent Progress to open the media details card.
Depending on the available metadata, the card can show artwork, an overview, runtime, certification, rating information, provider sources, progress, and links to TMDb or IMDb.
### Customizing widgets
Move the pointer over a widget to reveal its layout controls.
#### Change the order
Use the drag control to move a widget to another position.
Widgets automatically adjust to the available dashboard width.
#### Change the size
Use the size control to switch between compact and horizontal mode.
Compact widgets share the available dashboard columns.
Horizontal widgets use the full dashboard width.
#### Change the view
Compact widgets can use a grid or poster view.
Horizontal widgets can use media cards or a poster carousel.
Recent Playlists uses the poster carousel when displayed horizontally.
#### Hide a widget
Use the visibility control to hide a widget from the current layout.
#### Reset widget (unhide)
To restore hidden widgets, open the dashboard tools in the Sync Hub header and select the visibility button. This restores hidden Sync Hub blocks and dashboard widgets.
### Enabling widgets
Open **Settings → User Interface → Dashboard** to enable or disable individual widgets.
The following widgets are enabled by default:
* Watchlist
* Recent History
* Latest Ratings
* Recent Scrobble
The following widgets are disabled by default:
* Recent Progress
* Recent Playlists
A widget disabled in Settings cannot be restored using the dashboard visibility button. Enable it again under User Interface settings.
These settings only control the interface. They do not enable or disable the associated synchronization feature.
### Layout storage
Widget order, size, view, and locally hidden state are stored in the browser.
This allows different browsers and devices to use different dashboard layouts.
The Show or Hide settings under User Interface are stored in the CrossWatch configuration and apply to every browser using that CrossWatch installation.
Clearing browser storage resets the local widget layout.
### Refreshing widgets
CrossWatch refreshes dashboard data after relevant activity, such as a completed synchronization, a stopped scrobble, a manual history change, or a watchlist update.
Select the refresh button on any widget to force a reload of all currently active dashboard widgets.
The widgets are previews and only display the most recent available entries.
### Empty widgets
An empty widget is shown in a reduced state.
An empty widget does not necessarily indicate a problem. It can mean that the feature is not configured, no successful activity has been recorded yet, or no suitable data is available.
### Metadata and artwork
Configure the TMDb metadata provider to enable posters, backdrops, media details, and external media links.
The Watchlist widget requires TMDb metadata. Other widgets can still show activity without TMDb, but artwork and media details may be limited.
{% endtab %}
{% tab title="Power users" %}
### Power users
Most users should manage dashboard widgets through the interface. The options below are intended for manual configuration, API use, troubleshooting, and browser specific layouts.
#### Configuration keys
Widget availability is controlled under the `ui` section of `config.json`.
```json
{
"ui": {
"show_watchlist_preview": true,
"show_recent_history_widget": true,
"show_latest_ratings_widget": true,
"show_recent_scrobble_widget": true,
"show_recent_progress_widget": false,
"show_recent_playlists_widget": false
}
}
```
The default values are:
`show_watchlist_preview`, `true`
`show_recent_history_widget`, `true`
`show_latest_ratings_widget`, `true`
`show_recent_scrobble_widget`, `true`
`show_recent_progress_widget`, `false`
`show_recent_playlists_widget`, `false`
These settings determine whether a widget is available on the Main dashboard.
They are different from hiding a widget through the dashboard layout controls. A widget disabled in `config.json` is not loaded and cannot be restored using the visibility control.
Manual configuration changes should normally be followed by a CrossWatch restart or configuration reload.
#### Browser layout storage
Widget layout preferences are stored in browser local storage under:
```
cw.dashboardWidgets.layout.v3
```
The stored object contains one entry for each widget:
```json
{
"watchlist": {
"order": 0,
"size": "large",
"view": "icon",
"horizontalView": "media",
"hidden": false
},
"history": {
"order": 1,
"size": "small",
"view": "grid",
"horizontalView": "media",
"hidden": false
}
}
```
Supported properties:
`order`, determines the widget position
`size`, accepts `small` or `large`
`view`, accepts `grid` or `icon` for compact widgets
`horizontalView`, accepts `media` or `poster` for horizontal widgets
`hidden`, controls local visibility
The Recent Playlists widget always uses its poster layout when displayed horizontally.
Layout preferences are local to the browser. They are not written to `config.json` and are not synchronized between devices.
Clearing browser storage removes the custom layout and restores the default widget order, sizes, views, and visibility.
Editing the local storage value manually is possible, but invalid values are normalized or replaced with defaults when the dashboard loads.
#### Dashboard widgets API
Recent dashboard activity is available through:
```http
GET /api/dashboard/widgets
```
Supported query parameters:
`include`, comma separated widget names
`history_limit`, maximum Recent History entries
`ratings_limit`, maximum Latest Ratings entries
`scrobble_limit`, maximum Recent Scrobble entries
`progress_limit`, maximum Recent Progress entries
`playlists_limit`, maximum Recent Playlists entries
Each limit accepts a value from `1` through `24`.
Example:
```http
GET /api/dashboard/widgets?include=ratings,progress,playlists&ratings_limit=12&progress_limit=8&playlists_limit=8
```
Possible values for `include` are:
`history`
`ratings`
`scrobble`
`progress`
`playlists`
Only requested widgets are built and returned. This can reduce unnecessary provider state and activity processing.
Example response structure:
```json
{
"ok": true,
"latest_ratings": {
"items": [],
"total": 0
},
"recent_progress": {
"items": [],
"total": 0
},
"recent_playlists": {
"items": [],
"total": 0
}
}
```
The Watchlist widget is loaded through the separate Watchlist preview flow and is not included in `/api/dashboard/widgets`.
#### Data sources
Recent History combines provider state with CrossWatch tracker history.
Latest Ratings combines provider state with CrossWatch tracker ratings.
Recent Scrobble uses successful scrobble and history synchronization events.
Recent Progress combines provider progress state with CrossWatch tracker progress.
Recent Playlists uses playlist synchronization activity.
Duplicate media rows can be merged when CrossWatch can identify them as the same item. Available provider IDs, titles, years, episode numbers, timestamps, and mapping aliases can affect this process.
#### Refresh behaviour
The dashboard keeps recently rendered widget data while navigating between pages.
Widgets are marked for refresh after relevant activity, including synchronization completion, stopped scrobbles, manual history changes, Watchlist changes, and settings changes.
A manual refresh reloads all currently active dashboard widgets, not only the widget whose refresh button was selected.
Hidden or disabled widgets are excluded from the dashboard API request.
{% endtab %}
{% endtabs %}
---
# 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://wiki.crosswatch.app/crosswatch/main-dashboard/dashboard-widgets.md?ask=&goal=
```
`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.