---
title: "The refresh option"
manual: "Dashboard"
version: "main"
permalink: "https://docs.typo3.org/permalink/typo3/cms-dashboard:make-refreshable@main"
source: "Developer/MakeRefreshable.rst"
rendered: "2026-09-30T05:15:21+00:00"
---

# The refresh option {#make-refreshable}

In each widget the refresh option can be enabled. If the option is enabled the
widget displays a reload button in the top right corner. It can then be
refreshed via user interaction or via a javascript api.

To enable the refresh action button, you have to define the
`refreshAvailable` option in the `$options` part of the widget
registration. Below is an example of a RSS widget with the refresh option enabled.

```yaml
dashboard.widget.myOwnRSSWidget:
  class: 'TYPO3\CMS\Dashboard\Widgets\RssWidget'
  arguments:
    $options:
      rssFile: 'https://typo3.org/rss'
      lifeTime: 43200
      refreshAvailable: true
  tags:
    - name: dashboard.widget
      identifier: 'myOwnRSSWidget'
      groupNames: 'general'
      title: 'LLL:EXT:extension/Resources/Private/Language/locallang.xlf:widgets.myOwnRSSWidget.title'
      description: 'LLL:EXT:extension/Resources/Private/Language/locallang.xlf:widgets.myOwnRSSWidget.description'
      iconIdentifier: 'content-widget-rss'
      height: 'medium'
      width: 'medium'
```

> [!NOTE]
> In this example, the TYPO3 core `\TYPO3\CMS\Dashboard\Widgets\RssWidget`
> widget class is used. In case you have implemented own widget classes, you
> have to implement the `getOptions()` method, returning `$this->options`,
> to the corresponding classes. Otherwise the refresh option won't have any
> effect.

## Enable the refresh button {#refresh-button}

Widgets can render a refresh button to allow users to manually refresh them.

This is done by passing the value `['refreshAvailable'] = true;` back
via `getOptions()` method of the widget.

All TYPO3 Core widgets implement this behaviour and allow integrators to
configure the option:

-   **refreshAvailable**

    -   *Type:* boolean
    -   *Default:* `false`

    Boolean value, either `false` or `true`.

    Provides a refresh button to backend users to refresh the widget.
    If the option is omitted `false` is assumed.

## JavaScript API {#refresh-javascript}

It is possible for all widgets to dispatch an event, which will cause
the widget being refreshed. This is possible for all widgets on the dashboard
even when the `refreshAvailable` option is not defined, or set to `false`.
This will give developers the option to refresh the widgets whenever they think
it is appropriate.

To refresh a widget, dispatch the `widgetRefresh` event on the
widget container (the `div` element with the `dashboard-item` class).
You can identify the container by the data attribute `widget-hash`, which
is a unique hash for every widget, even if you have more widgets of the same
type on your dashboard.

A small example below:

```javascript
document
  .querySelector('[data-widget-hash="{your-unique-widget-hash}"]')
  .dispatchEvent(new Event('widgetRefresh', {bubbles: true}));
```

See [Providing custom JS](https://docs.typo3.org/permalink/typo3/cms-dashboard:implement-new-widget-custom-js@main) to learn how to add custom JavaScript.