---
product: "AG Studio"
title: "Drill Through"
description: "Open a detail report filtered to what the user right-clicked. Studio supplies the clicked item and the filters active on the widget, and your application chooses what to pass on, where the report opens and how the user returns."
framework: angular
version: "3.1.0"
related:
    - title: "Context Menu"
      url: "https://www.ag-grid.com/studio/angular/context-menu/"
    - title: "Popups"
      url: "https://www.ag-grid.com/studio/angular/popups/"
    - title: "Undo & Redo"
      url: "https://www.ag-grid.com/studio/angular/undo-redo/"
    - title: "Exporting"
      url: "https://www.ag-grid.com/studio/angular/exporting/"
llms: "https://www.ag-grid.com/studio/llms.txt"
---

# Drill Through

A drill through opens a detail report filtered to the item the user chose, such as a row in a table or a bar in a chart. Your application builds the filter and decides where the report opens: in place of the current one, in a popup, or anywhere else. Studio applies the filter to every widget in that report.

## Drill Through in Place

Right-click a sport in Medals by Sport, such as Swimming, and choose **Drill Through to Swimming**. The detail report replaces the summary report and shows only that sport.

#### Drill Through in Place

```ts
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component.ts';

const app = bootstrapApplication(AppComponent, {
    providers: [provideHttpClient()],
});
```

[Live example: Drill Through in Place](https://www.ag-grid.com/studio/examples/drill-through/drill-through-in-place/angular/)

The menu item action:

- Saves the summary report state with `api.getState()`.
- Sets the detail report state.
- Sets the `drillThrough` property to `{ filter: params.filter }`, the clicked item only.

Click **Go Back** to return. It restores the saved state and sets `drillThrough` to `undefined`.

A country selected in Medals by Country is not carried into the detail report, because the action passes only the clicked item. See [Choosing What to Pass On](https://www.ag-grid.com/studio/angular/drill-through/#choosing-what-to-pass-on) to apply it too.

## Triggering From the Context Menu

Anything in your application, such as a button or a link, can start a drill through by setting the `drillThrough` property. To start one from a right-click, return an item from `getContextMenuItems`, as described in [Context Menu](https://www.ag-grid.com/studio/angular/context-menu/), and in its action, set the `drillThrough` property:

```ts
<ag-studio
    [getContextMenuItems]="getContextMenuItems"
    /* other studio properties ... */ />

this.getContextMenuItems = (params) => {
    if (params.filter == null) {
        return [];
    }
    return [
        {
            name: 'Drill Through',
            action: () => params.api.setProperty('drillThrough', { filter: params.filter }),
        },
    ];
};
```

`params.filter` holds the field values of the clicked item. When the right-click is not on a row or data point, `params.filter` is not set, so the snippet returns no items and no menu opens. See [Using the Callback Params](https://www.ag-grid.com/studio/angular/context-menu/#using-the-callback-params) for the full list of params.

## The Drill-Through Filter

Set the `drillThrough` property with a `filter` to constrain the report to that filter:

```ts
<ag-studio
    [drillThrough]="drillThrough"
    /* other studio properties ... */ />

this.drillThrough = {
    filter: {
        field: { id: 'medals.sport' },
        operator: 'equals',
        value: 'Swimming',
    },
};
```

The filter constrains every widget in the report. The user sees it as a read-only card in the Filters Panel, and cannot edit or remove it. To see the card, drill through in the first example, then open the Filters Panel.

The filter is not included when the report's state is read or saved.

Set it when the report is created, or later with `api.setProperty('drillThrough', { filter })`. Clear it with `api.setProperty('drillThrough', undefined)`.

## Choosing What to Pass On

The context menu callback supplies two kinds of filter:

- `params.filter` holds the field values of the clicked item, such as the sport in a grid row.
- `params.getActiveFiltersForWidget()` returns the filters currently constraining the widget's data: `page` for the page filters, `widget` for the widget's own filters and `crossFilter` for selections made in other widgets. Selections the widget shows only as a highlight are in `crossFilterHighlight`.

Studio applies only the filter you pass to `drillThrough`, so your application chooses which of these to apply. Pass only the clicked item to show all of its data, whatever the user had filtered. Combine it with the active filters to show only the data the user was looking at.

Rank conditions, such as a top 10 filter, are not supported in a drill-through filter. Studio ignores them, applies the rest of the filter and reports a warning. Remove them before passing on widget filters.

The example below combines the clicked item with the page, widget and cross filters into one `AND` filter. It removes the rank condition of the Top Medals by Sport chart.

#### Drill Through with Active Filters

```ts
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component.ts';

const app = bootstrapApplication(AppComponent, {
    providers: [provideHttpClient()],
});
```

[Live example: Drill Through with Active Filters](https://www.ag-grid.com/studio/examples/drill-through/drill-through-active-filters/angular/)

Click a country in Medals by Country, then right-click Swimming in Medals by Sport and choose **Drill Through to Swimming**. The detail report shows only Swimming medals for that country. Open the Filters Panel to see both conditions on the read-only card. Click **Go Back** to return.

## Destination and Return

Studio applies the drill-through filter to the report it is given. Your application decides where the detail report opens and how the user returns.

### In Place

The [first example](https://www.ag-grid.com/studio/angular/drill-through/#drill-through-in-place) replaces the current report. It saves the report state before drilling through, and its **Go Back** button restores it and clears the `drillThrough` property.

### Popup

This example opens the detail report in a [Popup](https://www.ag-grid.com/studio/angular/popups/) titled Drill-Through Detail. The popup holds a second Studio that shares the data engine of the first. Right-click a sport in Medals by Sport, such as Swimming, and choose **Drill Through to Swimming** to open it.

#### Drill Through to Popup

```ts
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component.ts';

const app = bootstrapApplication(AppComponent, {
    providers: [provideHttpClient()],
});
```

[Live example: Drill Through to Popup](https://www.ag-grid.com/studio/examples/drill-through/drill-through-popup/angular/)

When the popup closes, the example calls `restoreFocusOnClose` so focus returns to the widget, as described in [Context Menu - Restoring Focus](https://www.ag-grid.com/studio/angular/context-menu/#restoring-focus).

> **Note**
>
> If launching Studio in a popup, override the [Min Width](https://www.ag-grid.com/studio/angular/studio-theme/#reference-AgStudioCoreThemeParams-studioMinWidth) and [Min Height](https://www.ag-grid.com/studio/angular/studio-theme/#reference-AgStudioCoreThemeParams-studioMinHeight) based on the size of the popup to avoid unnecessary scrollbars. The popup already has the Studio theming variables set from the parent Studio instance, which will override any set via the `theme` property in the popup instance. Set the theme variables on the popup instance via CSS, e.g. `--ag-studio-min-width: 0px; --ag-studio-min-height: 0px`. This is demonstrated in the example above.

### Custom

The menu item action can do anything your application needs. This action opens another page of the application and passes the clicked sport in the URL:

```ts
<ag-studio
    [getContextMenuItems]="getContextMenuItems"
    /* other studio properties ... */ />

this.getContextMenuItems = (params) => {
    const { filter } = params;
    if (filter == null) {
        return [];
    }
    // The clicked item is one condition, or an AND of one condition per field
    const conditions = filter.operator === 'AND' ? filter.conditions : [filter];
    const sportCondition = conditions.find((condition) => condition.field && condition.field.id === 'medals.sport');
    const sport = sportCondition && sportCondition.value;
    if (sport == null) {
        return [];
    }
    return [
        {
            name: `Drill Through to ${sport}`,
            action: () => window.location.assign(`/sports?sport=${encodeURIComponent(sport)}`),
        },
    ];
};
```

## Highlighting Rows in a Table

A table can show the drill-through rows in context instead of filtering them out. Set its **Drill Through > Mode** setting in the Compose Panel to Highlight, or set `format.drillThrough` to `'highlight'`. The table then shows every row, with the rows matching the drill-through filter selected. The setting appears only while the report has a `drillThrough` property.

The report below is opened with a drill-through filter on Swimming. The Filters Panel shows the filter as a read-only card. The Medal Table shows every row, with the Swimming rows selected. Gold Medals by Country is filtered to Swimming.

#### Drill-Through Highlight

```ts
import '@angular/compiler';
import { provideHttpClient } from '@angular/common/http';
import { bootstrapApplication } from '@angular/platform-browser';

import { AppComponent } from './app.component.ts';

const app = bootstrapApplication(AppComponent, {
    providers: [provideHttpClient()],
});
```

[Live example: Drill-Through Highlight](https://www.ag-grid.com/studio/examples/drill-through/drill-through-highlight/angular/)

To switch the mode, select the Medal Table, open the Compose Panel and change **Drill Through > Mode** between Filter and Highlight.

## Drill-Through API

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `drillThrough` | `AgDrillThroughOptions<TRegistry>` |  | Supplies an inbound drill-through filter to constrain the report, for example when the user has navigated in from another report or page. The filter is applied alongside the page filters on every data request, and is shown to the user in the Filters Panel, but cannot be edited or removed there. It is not included when the report's state is read or saved. Rank filters are not supported in a drill-through filter and are ignored with a warning. |

### Drill-Through Options

Properties available on the `AgDrillThroughOptions&lt;TRegistry extends AgCoreBaseRegistry = AgCoreDefaultRegistry&gt;` interface.

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `filter` | `AgFilterDefinition<TRegistry>` |  | A filter that constrains every data request the report makes, apart from a table widget whose Drill Through setting is set to highlight: such a table requests its full data set and shows the rows matching this filter as selected rows instead. Each condition names its own field, so a context may span several fields, for example `country` and `year` together. The filter is shown to the user in the Filters Panel, but cannot be edited or removed there, and is not included when the report's state is read or saved. Rank filters are not supported in a drill-through filter: any rank condition (`operator: 'rank'`) is ignored, the rest of the filter still applies, and a warning is reported. |