> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# Ranking filter

> Let users edit and apply a ranking filter to a visualization, or render the filter dropdown with a custom toggle button.

API reference: [RankingFilter()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.rankingfilter/index.md) (function, beta)

[`RankingFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.rankingfilter/index.md) is a dropdown that lets users create a ranking filter or edit an existing one. When a user clicks **Apply**, the `onApply` callback receives a ranking filter that you can pass to a visualization.

![RankingFilter toggle button and its open dropdown with Top or Bottom, a count, and a measure picker](https://www.gooddata.ai/docs/gooddata-ui/gd-ui/ranking_filter_combined.png)

## [Structure](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/ranking-filter/#structure)

```tsx
import "@gooddata/sdk-ui-filters/styles/css/main.css";
import { RankingFilter } from "@gooddata/sdk-ui-filters";

<RankingFilter
  onApply={<on-apply-callback>}
  onCancel={<on-cancel-callback>}
  filter={<filter>}
  buttonTitle={<toggle-button-title>}
  measureItems={<visualization-measures>}
  attributeItems={<visualization-attributes>}
/>
```

## [Example](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/ranking-filter/#example)

The following example shows a table displaying one measure sliced by one attribute. Users can filter the displayed rows with [`RankingFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.rankingfilter/index.md).

```tsx
import { FC, Fragment, useState } from "react";
import { PivotTable } from "@gooddata/sdk-ui-pivot";
import {
    attributeLocalId,
    localIdRef,
    measureLocalId,
    modifyAttribute,
    modifyMeasure,
    newRankingFilter,
} from "@gooddata/sdk-model";
import { RankingFilter, type IMeasureDropdownItem, type IAttributeDropdownItem } from "@gooddata/sdk-ui-filters";
import * as Md from "./catalog.js";

const FranchiseFees = modifyMeasure(Md.$FranchiseFees, (m) =>
    m.format("#,##0").localId("franchiseFees").title("Franchise Fees"),
);
const FranchisedSales = modifyMeasure(Md.$FranchisedSales, (m) =>
    m.format("#,##0").title("Franchise Sales").localId("franchiseSales"),
);
const LocationState = modifyAttribute(Md.LocationState, (a) => a.localId("LocationState"));
const LocationName = modifyAttribute(Md.LocationName.Default, (a) => a.localId("locationName"));

const measures = [FranchiseFees, FranchisedSales];
const attributes = [LocationState, LocationName];

const measureDropdownItems: IMeasureDropdownItem[] = [
    {
        title: "Franchise fees",
        ref: localIdRef(measureLocalId(FranchiseFees)),
        sequenceNumber: "M1",
    },
    {
        title: "Franchised sales",
        ref: localIdRef(measureLocalId(FranchisedSales)),
        sequenceNumber: "M2",
    },
];
const attributeDropdownItems: IAttributeDropdownItem[] = [
    {
        title: "Location state",
        ref: localIdRef(attributeLocalId(LocationState)),
        type: "ATTRIBUTE",
    },
    {
        title: "Location",
        ref: localIdRef(attributeLocalId(LocationName)),
        type: "ATTRIBUTE",
    },
];
export const RankingFilterExample: FC = () => {
    const [filter, setFilter] = useState(newRankingFilter(measureLocalId(FranchisedSales), "TOP", 3));
    return (
        <Fragment>
            <RankingFilter
                measureItems={measureDropdownItems}
                attributeItems={attributeDropdownItems}
                filter={filter}
                onApply={(filter) => setFilter(filter)}
                buttonTitle={"Ranking filter"}
            />
            <hr className="separator" />
            <div style={{ height: 300 }} className="s-pivot-table">
                <PivotTable measures={measures} rows={attributes} filters={[filter]} />
            </div>
        </Fragment>
    );
};
```

## [Custom toggle button](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/ranking-filter/#custom-toggle-button)

To toggle the filter dropdown with your own button, use [`RankingFilterDropdown`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.rankingfilterdropdown/index.md). It renders only the dropdown body, outside of the current DOM tree, using [portals](https://react.dev/reference/react-dom/createPortal).

![Custom toggle button with the ranking filter dropdown open below it](https://www.gooddata.ai/docs/gooddata-ui/gd-ui/ranking_filter_custom_button.png)

[`RankingFilterDropdown`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.rankingfilterdropdown/index.md) takes the same props as [`RankingFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.rankingfilter/index.md) (see [Props](#props)), with these differences:

- It has no `buttonTitle`.
- `onCancel` is required, because you use it to hide the dropdown.
- `anchorEl` (optional) sets the element the dropdown is aligned to, typically your toggle button. It takes an `HTMLElement` or a CSS selector string and defaults to `"body"`.

## [Props](https://www.gooddata.ai/docs/gooddata-ui/latest/filters/ranking-filter/#props)

| Prop | Type | Required | Description | Inherited from |
|------|------|----------|-------------|----------------|
| [`attributeItems`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.irankingfilterprops/index.md#irankingfilterpropsattributeitems) | [`IAttributeDropdownItem`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.iattributedropdownitem/index.md)`[]` | Yes | — | — |
| [`buttonTitle`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.irankingfilterprops/index.md#irankingfilterpropsbuttontitle) | `string` | Yes | — | — |
| [`filter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.irankingfilterprops/index.md#irankingfilterpropsfilter) | [`IRankingFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.irankingfilter/index.md) | Yes | — | — |
| [`measureItems`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.irankingfilterprops/index.md#irankingfilterpropsmeasureitems) | [`IMeasureDropdownItem`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.imeasuredropdownitem/index.md)`[]` | Yes | — | — |
| [`onApply`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.irankingfilterprops/index.md#irankingfilterpropsonapply) | `(filter:` [`IRankingFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.irankingfilter/index.md)`) => void` | Yes | — | — |
| [`customGranularitySelection`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.irankingfilterprops/index.md#irankingfilterpropscustomgranularityselection) | [`ICustomGranularitySelection`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.icustomgranularityselection/index.md) | No | — | — |
| [`locale`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.irankingfilterprops/index.md#irankingfilterpropslocale) | `string` | No | — | — |
| [`onCancel`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.irankingfilterprops/index.md#irankingfilterpropsoncancel) | `() => void` | No | — | — |
| [`onDropDownItemMouseOut`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.irankingfilterprops/index.md#irankingfilterpropsondropdownitemmouseout) | `() => void` | No | — | — |
| [`onDropDownItemMouseOver`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui-filters/sdk-ui-filters.irankingfilterprops/index.md#irankingfilterpropsondropdownitemmouseover) | `(ref:` [`ObjRefInScope`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.objrefinscope/index.md)`) => void` | No | — | — |