Dev Overlay Plugin API
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 plugins
Section titled Adding pluginsAstro Integrations can add plugins in the astro:config:setup
hook using the addDevOverlayPlugin
method.
Structure of a plugin
Section titled Structure of a pluginA plugin is a .js
or .ts
file that default exports an object with the following required properties:
id: string
Section titled id: stringA unique identifier for the plugin. This will be used to uniquely identify the plugin in hooks and events.
name: string
Section titled name: stringThe name of the plugin. This will be shown to users whenever the plugin needs to be referenced using a human-readable name.
icon: Icon
Section titled icon: IconThe 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.
init: (canvas: ShadowRoot, eventTarget: EventTarget) => void
Section titled init: (canvas: ShadowRoot, eventTarget: EventTarget) => voidThis 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:
canvas
Section titled canvasA 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.
eventTarget
Section titled eventTargetAn EventTarget
that can be used to send and receive events from the dev overlay.
beforeTogglingOff
Section titled beforeTogglingOffThis 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.
canvas
Section titled canvasThe ShadowRoot of the plugin, can be used to render any UI needed.
Client-side Events
Section titled Client-side EventsUsing the eventTarget
argument on the init
hook, plugins can send and receive events from the dev overlay. The following events are available:
plugin-toggled
Section titled plugin-toggledThis event is fired when the user clicks on the plugin icon in the dev overlay bar.
state: boolean
Section titled state: booleanIndicates whether or not the plugin is enabled after the user’s click.
toggle-notification
Section titled toggle-notificationThis event can be sent to inform the user that the plugin requires attention.
state: boolean
Section titled state: booleanIndicates 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.
toggle-plugin
Section titled toggle-pluginThis 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.
state: boolean
Section titled state: booleanIndicates 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 Communication
Section titled Client-Server CommunicationUsing 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:
astro-dev-overlay:PLUGIN_ID:initialized
Section titled astro-dev-overlay:PLUGIN_ID:initializedThis message is sent when the plugin is initialized. The data for this message is empty.
astro-dev-overlay:PLUGIN_ID:toggled
Section titled astro-dev-overlay:PLUGIN_ID:toggledThis 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 Toolkit
Section titled UI ToolkitThe dev overlay includes a set of web components that can be used to build plugins with a consistent look and feel.
astro-dev-overlay-window
Section titled astro-dev-overlay-windowShows a window.
The slot of the component will be used as the content of the window.
When building a window using JavaScript, slotted content must go inside the light DOM of the component.
astro-dev-overlay-button
Section titled astro-dev-overlay-buttonShows a button.
The slot of the component will be used as the content of the button.
The size of the button (small, medium, large).
button-style
Section titled button-styleThe style of the button (ghost
, outline
, purple
, gray
, red
). When using ghost
, the button itself is invisible and only the content of the button will be shown.
In JavaScript, set this property using the buttonStyle
property to avoid conflict with the native style
property.
astro-dev-overlay-badge
Section titled astro-dev-overlay-badgeShows a badge.
The slot of the component will be used as the content of the badge.
The size of the badge (small
, large
).
badge-style
Section titled badge-styleThe style (color) of the badge (purple
, gray
, red
, green
, yellow
).
In JavaScript, set this property using the buttonStyle
property to avoid conflict with the native style
property.
astro-dev-overlay-card
Section titled astro-dev-overlay-cardShows a card. Specify an optional link
attribute to make the card act like an <a>
element.
When making a card using using JavaScript, a clickAction
property can be specified to make the card act like a <button>
element.
The slot of the component will be used as the content of the card.
astro-dev-overlay-toggle
Section titled astro-dev-overlay-toggleShows 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 input
property.
astro-dev-overlay-highlight
Section titled astro-dev-overlay-highlightCan be used to highlight an element on the page. In most cases, you’ll want to position and resize this element using the top
, left
, width
and 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.
astro-dev-overlay-tooltip
Section titled astro-dev-overlay-tooltipShows a tooltip with different sections. This component is set to display: none;
by default and can be made visible using a data-show="true"
attribute.
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:
astro-dev-overlay-icon
Section titled astro-dev-overlay-iconShows an icon. An icon from the icon list can be specified using the icon
attribute, or the SVG markup of an icon can be passed as a slot.
Icons
Section titled IconsCurrently, the following icons are available and can be used in any component that accepts an icon:
astro:logo
warning
arrow-down
bug
file-search
check-circle
gear
lightbulb
file-search
checkmark
dots-three
copy
All of the above icons have fill="currentColor"
set by default and will inherit their color from the parent element.