The Astro Dev Overlay Plugin API allows you to create plugins that can be used to extend the Astro Dev Overlay. This allows you to add new features and integrations with third-party services.
Adding pluginsSection titled Adding plugins
Structure of a pluginSection titled Structure of a plugin
A plugin is a
.ts file that default exports an object with the following required properties:
Section titled id: string
A unique identifier for the plugin. This will be used to uniquely identify the plugin in hooks and events.
Section titled name: string
The name of the plugin. This will be shown to users whenever the plugin needs to be referenced using a human-readable name.
Section titled icon: Icon
The icon of the plugin. This will be used to display the plugin in the UI. This can either be an icon from the icon list, or a string containing the SVG markup of the icon.
Section titled init: (canvas: ShadowRoot, eventTarget: EventTarget) => void
init: (canvas: ShadowRoot, eventTarget: EventTarget) => void
This is the core part of the plugin. This function will be called when the plugin is loaded, which will either be when the browser is idle or when the user clicks on the plugin in the UI.
The function receives two arguments:
Section titled canvas
A ShadowRoot that the plugin can use to render its UI. Every plugin receive its own dedicated ShadowRoot for rendering its UI. Additionally, the parent element is positioned using
position: absolute; and as such, the plugin UI automatically won’t affect the layout of the page.
Section titled eventTarget
EventTarget that can be used to send and receive events from the dev overlay.
Section titled beforeTogglingOff
This optional function will be called when the user clicks on the plugin icon in the UI to toggle off the plugin. This function can be used, for example, to perform cleanup operations, do an animation, or to ask the user for confirmation before toggling off the plugin.
If a falsy value is returned, the toggling off will be cancelled and the plugin will stay enabled.
canvasSection titled canvas
The ShadowRoot of the plugin, can be used to render any UI needed.
Client-side EventsSection titled Client-side Events
Section titled plugin-toggled
This event is fired when the user clicks on the plugin icon in the dev overlay bar.
Indicates whether or not the plugin is enabled after the user’s click.
Section titled toggle-notification
This event can be sent to inform the user that the plugin requires attention.
Indicates whether or not the plugin has a notification for the user. When
true, the plugin icon will be highlighted using a red dot. Conversely, when
false, the highlight will be removed. If this property is not specified,
true will be assumed.
Section titled toggle-plugin
This event can be sent from your plugin to change the state of your plugin. This can be useful, for instance, to implement a “Close” button in your plugin’s UI.
Indicates whether or not the plugin should be enabled. When
true, the plugin will be enabled. Conversely, when
false, the plugin will be disabled. If this property is not specified,
true will be assumed.
Client-Server CommunicationSection titled Client-Server Communication
Using Vite’s methods for client-server communication, dev overlay plugins can communicate with the server.
In addition to being able to send and receive custom messages, the dev overlay also sends the following messages, where
PLUGIN_ID is the plugin’s ID:
Section titled astro-dev-overlay:PLUGIN_ID:initialized
This message is sent when the plugin is initialized. The data for this message is empty.
Section titled astro-dev-overlay:PLUGIN_ID:toggled
This message is sent when the user clicks on the plugin icon in the UI. The data for this message is a boolean indicating whether the plugin is enabled or not.
UI ToolkitSection titled UI Toolkit
The dev overlay includes a set of web components that can be used to build plugins with a consistent look and feel.
Section titled astro-dev-overlay-window
Shows a window with optionally a title and an icon.
window-title is a string that will be shown at the top of the overlay window.
window-icon can either be a string of a SVG file or an icon from the icon list.
The slot of the component will be used as the content of the window.
Section titled astro-dev-overlay-card
Shows a card with optionally an
icon. Optionally, if a
link is passed, the card will be clickable and will open the link in a new tab.
The slot of the component will be used as the content of the card.
Section titled astro-dev-overlay-toggle
Shows a toggle element, acting as a checkbox. This element internally is a simple wrapper around a native
<input type="checkbox"> element. The checkbox element can be accessed using the
Section titled astro-dev-overlay-highlight
Can be used to highlight an element on the page. In most cases, you’ll want to position and resize this element using the
height CSS properties to match the element you want to highlight. An icon can also be specified using the
icon attribute and will be shown in the top right corner of the highlight.
Section titled astro-dev-overlay-tooltip
Shows a tooltip with different sections. This component is set to
display: none; by default and can be made visible using a
Sections are defined using the
sections property. This property is an array of objects with the following shape:
This component is often combined with the
astro-dev-overlay-highlight component to show a tooltip when hovering a highlighted element:
IconsSection titled Icons
Currently, the following icons are available and can be used in any component that accepts an icon:
In addition to these included icons, you can also pass a string containing the SVG markup of the icon you want to use.