---
title: Embed Apps
description: >-
  Embed a published Datadog app in dashboards, notebooks, the Internal Developer
  Portal homepage, the Catalog side panel, APM service pages, and Agent
  Observability annotation queues.
breadcrumbs: Docs > Actions > Apps > Embed Apps
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Embed Apps

Embed [Datadog Apps](https://docs.datadoghq.com/actions/datadog_apps.md) in other Datadog products to place operational tools directly in the surfaces where users investigate issues and take action. An embedded app can display its existing experience or respond to live context supplied by its host, such as a dashboard's time range and template variables.

## Prerequisites{% #prerequisites %}

- A built, uploaded, and published Datadog app
- Permission to use the app and edit the destination surface

For information about building, uploading, and publishing an app, see [Datadog Apps](https://docs.datadoghq.com/actions/datadog_apps.md).

## Embed an app{% #embed-an-app %}

{% alert level="info" %}
You can embed an app only in the Datadog UI. AI agents cannot embed apps.
{% /alert %}

After you upload and publish an app, you can add it to a supported Datadog surface without changing the app.

You can embed an app from the app itself, or from the surface where you want it to appear.

### Embed from the app{% #embed-from-the-app %}

1. In the [App list](https://app.datadoghq.com/app-builder/apps/list), open the published app you want to embed.
1. At the top of the page, click **+ Add to Dashboard**, or click the down arrow next to it and select a destination type from the menu.
1. Select the destination, then click **Save**.

### Embed from the destination{% #embed-from-the-destination %}

{% tab title="Dashboard" %}

1. Open the dashboard where you want to add the app.
1. Click **Add Widgets** to open the widget tray.
1. Select the **Apps** tab, then drag the **Apps** widget onto the dashboard.
1. In the editor, choose the app from the **Select app** dropdown. To limit the list to apps you own, enable **My Apps Only**.
1. Resize the widget, then save the dashboard.

{% /tab %}

{% tab title="Notebook" %}

1. Open the notebook where you want to add the app.
1. Add a cell and select the **Apps** cell type.
1. Choose the app from the dropdown.
1. Save the notebook.

The **Apps** cell uses the notebook's time range. To read the time range in the app, use the `datadogNotebook` input.
{% /tab %}

{% tab title="Catalog side panel" %}

1. Navigate to [Catalog](https://app.datadoghq.com/services) and select a service.
1. In the service's side panel, select the **+ Add App** tab.
1. Choose the app from the dropdown. To limit the list to apps you own, enable **My Apps Only**.

{% /tab %}

{% tab title="APM service page" %}

1. Open the APM service page for the service.
1. In the left navigation, click **Add app** under the mode where you want the app to appear: **Info**, **Health**, **Govern**, or **Configuration**.
1. In the **Add an App** dialog, choose the app from the **Select an app** dropdown, then click **Add**.

The app appears as its own section in that mode. To read the service, environment, and time range in the app, use the `datadogServicePage` input.
{% /tab %}

{% tab title="Agent Observability annotation queue" %}

1. Open an interaction in an annotation queue.
1. Open the view menu.
1. Under **My Custom Views** or **All Custom Views**, select the app.

The app replaces the default display of the interaction. For more information, see [Annotation views](https://docs.datadoghq.com/llm_observability/investigate/annotation_queues.md#annotation-views). To read the trace and selected span in the app, use the `datadogAnnotationInteraction` input.
{% /tab %}

After you embed the app, optionally configure the app to respond to its host's context, theme, or shared-link state. Then verify it. An embedded app displays the most recently published version, so publish your changes before embedding.

## Customize the embedded experience{% #customize-the-embedded-experience %}

If you haven't already, install the [`@datadog/apps-frontend`](https://www.npmjs.com/package/@datadog/apps-frontend) package in the app:

```shell
npm install @datadog/apps-frontend
```

To make an embedded app respond to its Datadog host, keep `DatadogAppProvider` at the application root. The provider establishes communication with the Datadog host, makes host inputs available to hooks, and preserves the app's URL state in shared Datadog links.

```typescript
import { DatadogAppProvider } from '@datadog/apps-frontend/embedding/react';

export function Root() {
  return (
    <DatadogAppProvider>
      <App />
    </DatadogAppProvider>
  );
}
```

The standard Datadog Apps scaffold includes this provider by default. Every `@datadog/apps-frontend` hook must render below it, so keep the provider in place when you restructure the app.

### Read host inputs{% #read-host-inputs %}

Host inputs are values and functions supplied by the Datadog product containing the app. For example, a dashboard can provide its current time range and template variables, while the Catalog side panel can provide the service it is displaying.

Host values update automatically when the surrounding product context changes.

Import `useDatadogAppInput` and the input schema for the relevant product surface:

```typescript
import { useDatadogAppInput } from '@datadog/apps-frontend/inputs/react';
import {
  datadogAnnotationInteraction,
  datadogDashboard,
  datadogNotebook,
  datadogServicePage,
  datadogServicePanel,
  datadogTheme,
} from '@datadog/apps-frontend/inputs/schema';
```

For the complete TypeScript definitions, see the [`@datadog/apps-frontend` source on npm](https://www.npmjs.com/package/@datadog/apps-frontend?activeTab=code).

#### Input states{% #input-states %}

`useDatadogAppInput` returns a state object whose `status` is `pending`, `ready`, `unavailable`, or `failed`. Values are available in `fields` only when the status is `ready`.

`unavailable` is a normal outcome rather than an error. It means the app is running on a surface that does not provide that input, such as reading `datadogDashboard` inside a notebook. Render a fallback for this case.

For example:

```typescript
function PanelHeader() {
  const panel = useDatadogAppInput(datadogServicePanel);

  switch (panel.status) {
    case 'pending':
      return <Spinner />;
    case 'unavailable':
      return <p>Open this app from a Catalog side panel.</p>;
    case 'failed':
      return <p>{panel.error.message}</p>;
    case 'ready':
      return (
        <header>
          {panel.fields.service}
          <button onClick={() => panel.fields.close()}>×</button>
        </header>
      );
  }
}
```

### Available inputs{% #available-inputs %}

{% tab title="Theme" %}
Use `datadogTheme` to respond to the theme currently used by the Datadog host.

```typescript
const theme = useDatadogAppInput(datadogTheme);
```

When the status is `ready`, `fields` provides:

```typescript
{
  theme: 'light' | 'dark';
}
```

The value updates when the user changes the Datadog theme.

If the app uses [DRUIDS](https://docs.datadoghq.com/actions/datadog_apps.md#ui-components), you can use `DruidsEnvironmentWithThemeInput` to apply the host theme automatically:

```typescript
import { DruidsEnvironmentWithThemeInput } from '@datadog/apps-frontend/druids/react';

<DatadogAppProvider>
  <DruidsEnvironmentWithThemeInput defaultThemePreference="light">
    <App />
  </DruidsEnvironmentWithThemeInput>
</DatadogAppProvider>
```

{% /tab %}

{% tab title="Dashboard" %}
Use `datadogDashboard` to read a dashboard's current time range and template variables.

```typescript
const dashboard = useDatadogAppInput(datadogDashboard);
```

When the status is `ready`, `fields` provides:

```typescript
{
  dashboard: {
    timeframe: {
      start: number;
      end: number;
      isLive: boolean;
    };
    templateVariables: {
      name: string;
      value: string;
      values?: string[];
      prefix?: string;
      default?: string;
    }[];
  };
}
```

Use the time range to scope the app's queries to the dashboard. Use template variables to apply the same service, environment, team, or other filters used by the surrounding dashboard.
{% /tab %}

{% tab title="Notebook" %}
Use `datadogNotebook` to read a notebook's current time range and template variables.

```typescript
const notebook = useDatadogAppInput(datadogNotebook);
```

When the status is `ready`, `fields` provides:

```typescript
{
  notebook: {
    timeframe: {
      start: number;
      end: number;
      isLive: boolean;
    };
    templateVariables: {
      name: string;
      value: string;
      values?: string[];
      availableValues?: string[];
      prefix?: string;
      default?: string;
    }[];
  };
}
```

Use this context to keep the app synchronized with the time range and filters applied to the surrounding notebook.
{% /tab %}

{% tab title="Catalog side panel" %}
Use `datadogServicePanel` to identify the service displayed in the Catalog side panel.

```typescript
const servicePanel = useDatadogAppInput(datadogServicePanel);
```

When the status is `ready`, `fields` provides:

```typescript
{
  service: string;
  close: () => undefined;
}
```

Use `service` to scope the app's content to the selected service. Call `close()` when an app action should close the side panel.
{% /tab %}

{% tab title="APM service page" %}
Use `datadogServicePage` to read the service and filters shown on an APM service page.

```typescript
const servicePage = useDatadogAppInput(datadogServicePage);
```

When the status is `ready`, `fields` provides:

```typescript
{
  scopeFilter: {
    service: string;
    // null when the page shows every environment.
    env: string | null;
    // null when the page shows every version.
    version: string | null;
    // Empty when the page shows every operation.
    operationName: string;
    // For example, 'server' or 'consumer'. null when the page doesn't filter by span kind.
    spanKind: string | null;
    primaryTags: {
      field: string;
      value: string | null;
    }[];
    // Unix timestamps in milliseconds.
    timeFrame: {
      start: number;
      end: number;
    };
  };
}
```

Use `scopeFilter` to limit the app's queries to the service, environment, and time range the user is viewing. The values update when the user changes the page's filters or time range.
{% /tab %}

{% tab title="Agent Observability annotation queue" %}
Use `datadogAnnotationInteraction` to read the trace under review in an [annotation queue](https://docs.datadoghq.com/llm_observability/investigate/annotation_queues.md#annotation-views) and the span the reviewer selected. The input is read-only.

```typescript
const input = useDatadogAppInput(datadogAnnotationInteraction);
```

When the status is `ready`, `fields` provides:

```typescript
{
  annotationInteraction:
    | { status: 'loading'; traceId: string; spanId: string }
    | { status: 'unavailable'; traceId: string; spanId: string }
    | { status: 'ready'; traceId: string; spanId: string; trace: Trace };
}
```

`annotationInteraction` has its own `status`, separate from the input state. A `ready` input state means the app is connected to an annotation queue. The trace itself can still be loading, so check `annotationInteraction.status`:

- `loading`: The trace or the selected span's content is still loading.
- `unavailable`: The trace or the selected span's content can't be loaded, for example, because it is outside the retention period. Render a fallback that identifies the interaction with `traceId` and `spanId`.
- `ready`: `trace` contains the interaction's spans.

`trace` has the following shape:

```typescript
{
  root_id: string;
  // When true, spans other than the selected span can contain truncated content.
  is_preview?: boolean;
  // Keyed by span ID.
  spans: Record<string, {
    trace_id: string;
    span_id: string;
    parent_id?: string | null;
    children_ids?: string[] | null;
    name?: string | null;
    service?: string | null;
    resource?: string | null;
    status?: string | null;
    error?: number | null;
    // Timestamps and durations are in seconds.
    start: number;
    end?: number | null;
    duration?: number | null;
    meta?: {
      span?: { kind?: string | null } | null;
      input?: unknown;
      output?: unknown;
      metadata?: unknown;
      model_name?: string | null;
      model_provider?: string | null;
    } | null;
    metrics?: Record<string, number | string | boolean> | null;
  }>;
}
```

Use `spanId` to find the selected span in `trace.spans`. The full trace is always provided, and `spanId` does not limit it. The selected span's content is complete even when `is_preview` is `true`. The values update when the reviewer selects another span or moves to another interaction.

The trace type lists only some fields. Spans, `meta`, and `trace` also keep any additional instrumented fields, so the app can read data that the type does not list.
{% /tab %}

Do not assume that an input available on one product surface is available on another. Request only the context the app needs and provide a useful experience when that context is absent.

## Preserve state in shared links{% #preserve-state-in-shared-links %}

`DatadogAppProvider` preserves the app's query string and URL fragment in shared Datadog links. Store shareable state—such as selected services, filters, records, or in-app routes—in the URL. When another user opens the shared link, the embedded app can restore the same state. [Deep links](https://docs.datadoghq.com/actions/datadog_apps.md#share-embedded-app-state-with-deep-links) to a specific app state work without additional configuration, as long as the app remains wrapped in `DatadogAppProvider`.

## Verify the app{% #verify-the-app %}

After you embed the app, check the following on the surface where you embedded it:

- **Access**: Open the surface as a user who has permission to use the app but did not embed it. The app renders instead of a permission error.
- **Size**: Resize the app to the smallest size you expect users to configure. Content stays readable, without overflow or clipping.
- **Host context**: Change the host's context, such as a dashboard's time range or a template variable value, and confirm that the app updates. If the app renders its `unavailable` fallback instead, it is reading an input that the surface does not provide.
- **Shared links**: Change the state inside the app, copy the Datadog share link, and open it in a new browser session. The app restores the same state.

## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Datadog Apps](https://docs.datadoghq.com/actions/datadog_apps.md)
- [Embed App Builder Apps](https://docs.datadoghq.com/actions/app_builder/embedded_apps.md)
- [@datadog/apps-frontend package on npm](https://www.npmjs.com/package/@datadog/apps-frontend)
