> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# useDashboardEventDispatch

> Dispatch built-in or custom dashboard events from a plugin component with the alpha useDashboardEventDispatch hook.

API reference: [useDashboardEventDispatch()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.usedashboardeventdispatch/index.md) (function, alpha)

`useDashboardEventDispatch` returns a function that sends a built-in or custom event to the dashboard event bus from a plugin component.

> **Alpha API:**
> `useDashboardEventDispatch` is `@alpha` and may change. For a public alternative, dispatch the `@beta` `triggerEvent`
> command through the public [`useDispatchDashboardCommand`](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard/index.md#commands) hook:
> `useDispatchDashboardCommand(triggerEvent)`.

## [Basic usage](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-event-dispatch/#basic-usage)

```tsx
import { useDashboardEventDispatch } from "@gooddata/sdk-ui-dashboard";

export const NotifyButton = () => {
    const dispatchEvent = useDashboardEventDispatch();

    return (
        <button onClick={() => dispatchEvent({ type: "CUSTOM/EVT/MY_WIDGET_CLICKED", payload: { source: "notify" } })}>
            Notify
        </button>
    );
};
```

Handle the event like any other, for example with a custom event handler in a plugin; see [Handle dashboard events](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/dashboard-events/index.md).

## [Return value](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-event-dispatch/#return-value)

`(eventBody: DashboardEventBody<DashboardEvents | ICustomDashboardEvent>) => void`: a function that wraps the event in the `triggerEvent` command and dispatches it. [`DashboardEventBody`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboardeventbody/index.md) is the event without its `ctx`; the dashboard adds the context.

## [Notes](https://www.gooddata.ai/docs/gooddata-ui/latest/dashboard-plugins/use-dashboard-event-dispatch/#notes)

- The event `type` must start with `GDC.DASH/EVT` (a built-in event) or `CUSTOM/EVT` (a custom event). Any other value fails an invariant: "Unsupported event passed to useDashboardEventDispatch result."
- Call the hook inside a component rendered by the [`Dashboard`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-dashboard/sdk-ui-dashboard.dashboard/index.md) component.