diff --git a/src/content/docs/en/reference/dev-toolbar-app-reference.mdx b/src/content/docs/en/reference/dev-toolbar-app-reference.mdx
index 3f16c8b45ca45..fe2c242113c2b 100644
--- a/src/content/docs/en/reference/dev-toolbar-app-reference.mdx
+++ b/src/content/docs/en/reference/dev-toolbar-app-reference.mdx
@@ -3,7 +3,6 @@ title: Dev Toolbar App API
i18nReady: true
---
import Since from '~/components/Since.astro';
-
import RecipeLinks from "~/components/RecipeLinks.astro";
The Astro Dev Toolbar App API allows you to create [Astro Integrations](/en/reference/integrations-reference/) that add apps to the Astro Dev Toolbar. This allows you to add new features and integrations with third-party services.
@@ -35,10 +34,21 @@ export default () => ({
### `addDevToolbarApp()`
-A function available to [the `astro:config:setup` hook](/en/reference/integrations-reference/#astroconfigsetup) that adds dev toolbar apps. It takes an object with the following required properties to define the toolbar app: [`id`](#id), [`name`](#name), [`icon`](#icon), and [`entrypoint`](#entrypoint).
+
+
+A function available to [the `astro:config:setup` hook](/en/reference/integrations-reference/#astroconfigsetup) that adds dev toolbar apps. It takes an object with the following required properties to define the toolbar app: [`id`](#id), [`name`](#name), and [`entrypoint`](#entrypoint). Optionally, you can also define an [`icon`](#icon) for your app.
### `id`
+
+
+**Type:** `string`
+
+
A unique identifier for the app. This will be used to uniquely identify the app in hooks and events.
```ts title="my-integration.js" {2}
@@ -50,6 +60,11 @@ A unique identifier for the app. This will be used to uniquely identify the app
### `name`
+
+
+**Type:** `string`
+
+
The name of the app. This will be shown to users whenever the app needs to be referenced using a human-readable name.
```ts title="my-integration.js" {3}
@@ -62,6 +77,12 @@ The name of the app. This will be shown to users whenever the app needs to be re
### `icon`
+
+
The icon used to display the app in the toolbar. This can either be an icon from [the icon list](#icons), or a string containing the SVG markup of the icon.
```ts title="my-integration.js" {3}
@@ -74,6 +95,11 @@ The icon used to display the app in the toolbar. This can either be an icon from
### `entrypoint`
+
+
+**Type:** `string | URL`
+
+
The path to the file that exports the dev toolbar app.
```ts title="my-integration.js" {3}
@@ -127,7 +153,11 @@ export default defineToolbarApp({
```
### `defineToolbarApp()`
-
A function that defines the logic of your toolbar app when it is loaded and toggled off.
@@ -135,7 +165,10 @@ This function takes an object with an [`init()`](#init) function that will be ca
### `init()`
-**Signature:** `init(canvas: ShadowRoot, app: ToolbarAppEventTarget, server: ToolbarServerHelpers) => void`
+
Although not required, most apps will use this function to define the core behavior of the app. This function will be called only once 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, depending on which one comes first.
@@ -143,6 +176,11 @@ The function receives three arguments to define your app logic: [`canvas`](#canv
#### `canvas`
+
+
+**Type:** `ShadowRoot`
+
+
A standard [ShadowRoot](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) that the app can use to render its UI. Elements can be created and added to the ShadowRoot using the standard DOM APIs.
Every app receives its own dedicated ShadowRoot for rendering its UI. Additionally, the parent element is positioned using `position: absolute;` so the app UI will not affect the layout of an Astro page.
@@ -157,11 +195,15 @@ export default defineToolbarApp({
#### `app`
-
+
+
+**Type:** `ToolbarAppEventTarget`
+
+
A standard [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) with a few additional [helpers for client-side events](#client-side-events) that can be used to send and receive events from the Dev toolbar.
-```ts title="src/my-app.js" {3-6}
+```ts title="src/my-app.js" {3-8}
export default defineToolbarApp({
init(canvas, app) {
app.onToggled(({ state }) => {
@@ -176,7 +218,11 @@ export default defineToolbarApp({
#### `server`
-
+
+
+**Type:** `ToolbarServerHelpers`
+
+
An object that can be used to [communicate with the server](#client-server-communication).
@@ -194,8 +240,11 @@ export default defineToolbarApp({
### `beforeTogglingOff()`
-**Signature:** `beforeTogglingOff(canvas: ShadowRoot): boolean | void`
-
+
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, or to ask the user for confirmation before toggling off the app.
@@ -213,6 +262,11 @@ export default defineToolbarApp({
#### canvas
+
+
+**Type:** `ShadowRoot`
+
+
The ShadowRoot of the app, can be used to render any UI needed before closing. Same as the [`canvas` argument of the `init` function](#canvas).
## Client-side Events
@@ -221,8 +275,11 @@ In addition to the standard methods of an `EventTarget` ([`addEventListener`](ht
### `onToggled()`
-**Signature:** `onToggled(callback: (options: {state: boolean})) => void`
-
+
Registers a callback to be called when the user clicks on the app icon in the UI to toggle the app on or off.
@@ -234,8 +291,11 @@ app.onToggled((options) => {
### `onToolbarPlacementUpdated()`
-**Signature:** `onToolbarPlacementUpdated(callback: (options: {placement: 'bottom-left' | 'bottom-center' | 'bottom-right'})) => void`
-
+
This event is fired when the user changes the placement of the Dev Toolbar. This can, for example, be used to reposition the app's UI when the toolbar is moved.
@@ -247,8 +307,11 @@ app.onToolbarPlacementUpdated((options) => {
### `toggleState()`
-**Signature:** `toggleState(options: {state: boolean}) => void`
-
+
Changes the state of the app. This can be used to enable or disable the app programmatically, for example, when the user clicks on a button in the app's UI.
@@ -258,8 +321,11 @@ app.toggleState({ state: false });
### `toggleNotification()`
-**Signature:** `toggleNotification(options: {state?: boolean, level?: 'error' | 'warning' | 'info'}) => void`
-
+
Toggles a notification on the app icon. This can be used to inform the user that the app requires attention, or remove the current notification.
@@ -270,11 +336,22 @@ app.toggleNotification({
});
```
-#### `state: boolean`
+#### `state`
+
+
+
+**Type:** `boolean`
+
Indicates whether or not the app has a notification for the user. When `true`, the app icon will be highlighted. Conversely, when `false`, the highlight will be removed. If this property is not specified, `true` will be assumed.
-#### `level: 'error' | 'warning' | 'info'`
+#### `level`
+
+
Indicates the level of the notification. This will be used to determine the color and shape (dark pink circle, gold triangle, or blue square) of the highlight on the app icon. If this property is not specified, `'error'` will be assumed.
@@ -300,8 +377,11 @@ export default defineToolbarApp({
#### `send()`
-**Signature:** `send(event: stringify, data: T) => void`
+
Sends data to the server from logic defined in your toolbar app.
@@ -315,8 +395,11 @@ When sending messages from the client to the server, it is good practice to pref
#### `on()`
-**Signature:** `on(event: string, callback: (data: T) => void) => void`
-
+
Registers a callback to be called when the server sends a message with the specified event.
@@ -344,8 +427,11 @@ export default () => ({
#### `send()`
-**Signature:** `send(event: string, data: T) => void`
-
+
Sends data to the client.
@@ -357,8 +443,11 @@ Sends data to the client.
#### `on()`
-**Signature:** `on(event: string, callback: (data: T) => void) => void`
-
+
Registers a callback to be called when the client sends a message with the specified event.
@@ -370,29 +459,35 @@ Registers a callback to be called when the client sends a message with the speci
},
```
-#### `onInitialized()`
+#### `onAppInitialized()`
-**Signature:** `onInitialized(appId: string, callback: () => void) => void`
-
+
Registers a callback to be called when the app is initialized.
```ts title="my-integration.js"
'astro:server:setup': ({ toolbar }) => {
- toolbar.onInitialized('my-app', () => {
+ toolbar.onAppInitialized('my-app', () => {
console.log('The app is now initialized!');
});
},
```
:::note
-The built-in `connection` event from Vite fires **before** Dev Toolbar apps are initialized and therefore cannot be used directly by apps. Use the `onInitialized` method to ensure that the app is fully initialized before sending messages to it.
+The built-in `connection` event from Vite fires **before** Dev Toolbar apps are initialized and therefore cannot be used directly by apps. Use the `onAppInitialized` method to ensure that the app is fully initialized before sending messages to it.
:::
#### `onAppToggled()`
-**Signature:** `onAppToggled(appId: string, callback: (options: {state: boolean}) => void) => void`
-
+
Registers a callback to be called when the user clicks on the app icon in the UI to toggle the app on or off.
@@ -450,19 +545,36 @@ myButton.addEventListener('click', () => {
#### `size`
-The size of the button (`small`, `medium`, `large`).
+
+
+The size of the button.
#### `button-style`
-The style of the button (`ghost`, `outline`, `purple`, `gray`, `red`, `green`, `yellow`, `blue`). When using `ghost`, the button itself is invisible and only the content of the button will be shown.
+
+
+The style of the button. 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.
#### `button-border-radius`
-
+
-The border radius of the button (`normal`, `rounded`). When using `rounded`, the button will have rounded corners and uniform padding on all sides.
+**Type:** `"normal" | "rounded"`
+**Default:** `"normal"`
+
+
+
+The border radius of the button. When using `rounded`, the button will have rounded corners and uniform padding on all sides.
In JavaScript, set this property using the `buttonBorderRadius` property.
@@ -478,11 +590,23 @@ The slot of the component will be used as the content of the badge.
#### `size`
-The size of the badge (`small`, `large`).
+