Dev Toolbar App API
Ce contenu n’est pas encore disponible dans votre langue.
The Astro Dev Toolbar App API allows you to create apps that can be used to extend the Astro Dev Toolbar. This allows you to add new features and integrations with third-party services.
Adding appsSection titled Adding apps
Structure of a Dev Toolbar AppSection titled Structure of a Dev Toolbar App
A Dev Toolbar App is a
.ts file that default exports an object with the following required properties:
Section titled id: string
A unique identifier for the app. This will be used to uniquely identify the app in hooks and events.
Section titled name: string
The name of the app. This will be shown to users whenever the app needs to be referenced using a human-readable name.
Section titled icon: Icon
The icon of the app. This will be used to display the app 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 app. This function will be called when the app is loaded, which will either be when the browser is idle or when the user clicks on the app in the UI.
The function receives two arguments:
Section titled canvas
A ShadowRoot that the app can use to render its UI. Every app receives its own dedicated ShadowRoot for rendering its UI. Additionally, the parent element is positioned using
position: absolute; and as such, the app 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 Toolbar.
Section titled beforeTogglingOff
This optional function will be called when the user clicks on the app icon in the UI to toggle off the app. 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 app.
If a falsy value is returned, the toggling off will be cancelled and the app will stay enabled.
canvasSection titled canvas
The ShadowRoot of the app, can be used to render any UI needed.
Client-side EventsSection titled Client-side Events
Section titled app-toggled
This event is fired when the user clicks on the app icon in the Dev Toolbar.
Indicates whether or not the app is enabled after the user’s click.
Section titled toggle-notification
This event can be sent to inform the user that the app requires attention.
Indicates whether or not the app has a notification for the user. When
true, the app 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-app
This event can be sent from your app to change the state of your app. This can be useful, for instance, to implement a “Close” button in your app’s UI.
Indicates whether or not the app should be enabled. When
true, the app will be enabled. Conversely, when
false, the app 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 Toolbar Apps can communicate with the server.
In addition to being able to send and receive custom messages, the Dev Toolbar also sends the following messages, where
APP_ID is the app’s ID:
Section titled astro-dev-toolbar:APP_ID:initialized
This message is sent when the app is initialized. The data for this message is empty.
Section titled astro-dev-toolbar:APP_ID:toggled
This message is sent when the user clicks on the app icon in the UI. The data for this message is a boolean indicating whether the app is enabled or not.
connection event from Vite fires before Dev Toolbar apps are initialized and therefore cannot be used directly by apps. Instead, use the
UI ToolkitSection titled UI Toolkit
The Dev Toolbar includes a set of web components that can be used to build apps with a consistent look and feel.
Section titled astro-dev-toolbar-window
Shows a window.
The slot of the component will be used as the content of the window.
Section titled astro-dev-toolbar-button
Shows a button.
The slot of the component will be used as the content of the button.
The size of the button (
Section titled button-style
The style of the button (
red). When using
ghost, the button itself is invisible and only the content of the button will be shown.
buttonStyle property to avoid conflict with the native
Section titled astro-dev-toolbar-badge
Shows a badge.
The slot of the component will be used as the content of the badge.
The size of the badge (
Section titled badge-style
The style (color) of the badge (
badgeStyle property to avoid conflict with the native
Section titled astro-dev-toolbar-card
Shows a card. Specify an optional
link attribute to make the card act like an
clickAction property can be specified to make the card act like a
The slot of the component will be used as the content of the card.
Section titled astro-dev-toolbar-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-toolbar-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-toolbar-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-toolbar-highlight component to show a tooltip when hovering a highlighted element:
Section titled astro-dev-toolbar-icon
Shows 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.
IconsSection titled Icons
Currently, the following icons are available and can be used in any component that accepts an icon:
All of the above icons have
fill="currentColor" set by default and will inherit their color from the parent element.