Skip to content

JavaScript Event Reference

The Hyvä admin dashboard runs on a browser JavaScript event system. Instead of calling each other directly, dashboard components talk by dispatching and listening for custom events. That keeps widgets, the view switcher, and the dashboard grid loosely coupled, so you can hook into almost any interaction without patching core code.

This page is the reference for every event the admin dashboard modules dispatch: what fires it, what it does, and what its event detail carries.

Placeholder Tokens in Event Names

Some event names contain placeholder tokens such as {{WIDGET_TYPE_ID}} or {{INSTANCE_ID}}. At runtime these are replaced with a concrete value, for example configure-widget-type-conversion_rate. Underscores (_) inside the substituted values are converted to dashes (-).

Widget Configuration Form Events

These events drive the widget configuration form modal - the form the admin user fills in when creating a new widget instance or editing an existing one. They cover opening the form, closing it, and handling unsaved changes.

configure-widget-type-{{WIDGET_TYPE_ID}}

Fired when the admin user selects a widget type to create or chooses to edit an existing widget instance. It triggers the display of the widget configuration form modal.

When configuring a new widget instance, {{WIDGET_TYPE_ID}} is replaced with the relevant widget type ID, for example conversion_rate or recent_orders.

When editing the configuration of an existing widget instance, {{WIDGET_TYPE_ID}} is replaced with the relevant widget instance ID.

new-widget-menu

Fired when the admin user clicks the Add Widget button. It displays the widget selection modal where the admin user picks a widget type to add.

force-close-widget-config-form

Fired when the admin user clicks the Cancel button in the customization toolbar while any of the widget configuration forms have unsaved changes.

widget-config-form-open

Fired when the admin user opens the widget configuration modal for an existing widget instance.

widget-config-form-close

Fired when the admin user closes the widget configuration modal for an existing widget instance.

widget-config-form-dirty-close

Fired when the admin user closes the widget configuration modal while it has unsaved changes. It triggers the confirmation modal that prompts the admin user to confirm they are happy to lose their unsaved changes.

widget-config-form-reset

Fired when the admin user closes the widget configuration modal.

Widget Instance Events

These events fire around individual widget instances: when a new instance is created, when its content or configuration updates, and when instance-level controls such as property switchers and filters change. Several carry the widget instance ID in their event detail so listeners know which widget to update.

widget-instance-created

Fired when the widget configuration form for a new widget instance has been saved successfully. It tells the widget container component to insert a new widget.

widget-instance-data-updated

Fired when a widget instance successfully has its content updated. This happens once when the widget component is first initialized, and again whenever the admin user updates its configuration.

widget-instance-updated-{{WIDGET_INSTANCE_ID}}

Fired when the widget configuration form for an existing widget instance has been saved successfully. It tells the widget container component to update the widget content for the widget whose instance ID matches {{WIDGET_INSTANCE_ID}}.

widget-instance-{{INSTANCE_ID}}-{{PROPERTY_TYPE}}-{{INPUT_NAME}}-updated

Fired by the widget instance property switcher component whenever the admin user changes the selected value.

String Replacement

Underscores (_) in any of the {{INSTANCE_ID}}, {{PROPERTY_TYPE}}, and {{INPUT_NAME}} values are replaced by dashes (-).

Property Switcher

The property switcher component is most often found in the header of the widget instance output. The core Hyvä admin dashboard widgets use this component for things like the interval value switcher seen on some sales-related widgets.

widget-filter-update

Fired by the framework filter action component when the admin user selects a filter option. It notifies widget instances to update their displayed content based on the selected filter value.

The event detail contains the widget instance ID and the selected filter value: {id: instanceId, value: selectedFilter}.

sort-checklist-items

Fired by the checklist widget's sort action component. It triggers the reordering of checklist items so that completed items are moved to the bottom of the list.

The event detail contains the widget instance ID: {id: instanceId}.

Widget Container and Edit Mode Events

These events coordinate the widget container and the dashboard "Edit Mode", where the admin user repositions and resizes widgets. They cover enabling and disabling edit mode, saving or discarding layout changes, and container lifecycle notifications.

enabled-widget-container-edit-mode

Fired when the admin user enables the dashboard "Edit Mode" by clicking either the widget menu's Resize action or the dashboard toolbar's customize Dashboard button.

See the Dashboard Organisation user guide for more information.

disabled-widget-container-edit-mode

Fired when the admin user disables the dashboard "Edit Mode" by saving their positioning and sizing changes.

See the Dashboard Organisation user guide for more information.

widget-container-edit-mode-enabled

Fired by the widget container when "Edit Mode" is enabled. It disables the customize Dashboard button.

See the Dashboard Organisation user guide for more information.

widget-container-edit-mode-disabled

Fired by the widget container when "Edit Mode" is disabled. It re-enables the customize Dashboard button after the admin user has saved their positioning and sizing changes.

See the Dashboard Organisation user guide for more information.

widget-container-initialised

Fired by the widget container once it has initialized.

widget-container-updated

Fired by the widget container once it has initialized, and whenever a widget is added to or removed from it.

reset-widget-order

Fired when the admin user clicks the Cancel button in the customization toolbar. It restores the dashboard to its last stable state.

widget-dashboard-clear

Fired when the admin user opts to clear their dashboard. It opens the modal the admin user can use to either cancel or confirm the action.

Dashboard View Events

These events power dashboard views: the named layouts an admin user can create, switch between, share via roles, and delete. Many carry the affected view's metadata in their event detail so the view switcher can keep its list in sync.

create-new-dashboard-view

Fired when the admin user chooses to create a new view from the view-switcher menu. Opens the new-view form modal. See the Dashboard Views user guide for more information.

dashboard-view-new-modal-open

Fired by the view-switcher menu when the admin user clicks Create View. Opens the new-view form modal.

dashboard-view-edit-modal-open

Fired when the admin user opens the edit-view form modal for the active view.

dashboard-view-duplicate-modal-open

Fired by the view-switcher menu to open the duplicate-view form modal. The event detail identifies the source view to duplicate.

dashboard-view-delete-modal-open

Fired by the view-switcher menu to open the delete-confirmation modal. The event detail identifies the view that is about to be deleted.

dashboard-view-loaded

Fired after the dashboard View/Load controller has returned the widget instances for the active view and the dashboard grid has rendered them. Use this event as a hook for any per-view widget initialization logic.

dashboard-view-changed

Fired when the active view changes, either because the admin user picked a different view from the switcher or because a draft was saved against the active view. The event detail contains the new view metadata so listeners can refresh their state.

dashboard-view-saved

Fired after a view has been saved through the View/Save controller. The event detail contains the saved view's metadata. Used by the view switcher to reflect renames and role-assignment changes.

dashboard-view-deleted

Fired after a view has been deleted via the dashboard View/Delete controller. The event detail identifies the removed view so listeners (notably the view switcher) can drop it from their lists.

dashboard-view-permissions-changed

Fired when the admin user changes the role assignments on a view. Listeners refresh the role-assignment UI and recompute whether the view is shared.

dashboard-view-access-revoked

Fired when the active view becomes inaccessible to the current admin user (for example, when a role-assigned view is unassigned from the user's role mid-session). Listeners should redirect the dashboard back to the user's default view.

dashboard-view-switch-proceed

Fired by the unsaved-changes confirmation modal when the admin user confirms they want to discard pending changes and switch to a different view. The event detail identifies the destination view.

dashboard-view-switch-failed

Fired when an attempted view switch fails, typically because the destination view has been deleted by another admin user or because the current user lost access to it. Listeners surface a toast and revert the switcher to the previously active view.

Chart Events

These events relate to the ApexCharts-based widgets on the dashboard: knowing when the charting library is ready, and keeping chart sizes in sync when widgets are resized or opened full screen.

dashboard-charts-ready

Fired once the ApexCharts library has loaded and is available through the window.ApexCharts object.

See our ApexCharts documentation for more information.

update-chart-size-{{INSTANCE_ID}}

Fired when the admin user opens or closes the full screen view of a widget, or when a widget is resized in a way that requires the widget chart size to update.

General UI Events

These events cover dashboard-wide user interface feedback that is not tied to a single widget or view.

update-toast

Fired whenever a message needs to be surfaced to the admin user, usually to highlight a successful or failing action.