Attribute filter button

Configure AttributeFilterButton with a filter definition or placeholder, handle selected values, choose single or multiple selection, and replace its UI components.

AttributeFilterButton is a dropdown that lists the values of an attribute. Its button shows the attribute name together with the current selection.

You can connect the component in one of two ways:

Pass a filter and an onApply callback. The callback receives the updated filter when a user clicks Apply.
Pass a visualization definition placeholder in connectToPlaceholder. The component reads and writes the placeholder value itself, so onApply is optional.

Identify elements by value

GoodData Cloud and GoodData.CN identify attribute elements by their primary key, which equals the element title. Pass element values, for example newPositiveAttributeFilter(Md.EmployeeName.Default, ["Abbie Adams"]). The { uris: [...] } form is a legacy form: these backends treat its items as primary key values too.

Structure

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

<AttributeFilterButton
    filter={<attribute-filter>}
    onApply={<on-apply-callback>}
    selectionMode={<"multi" | "single">}
    attributeFilterMode={<"active" | "readonly" | "hidden">}
    parentFilters={<parent-filters>}
    parentFilterOverAttribute={<connecting-attribute>}
/>;

Example

The filter starts with nothing excluded. When a user clicks Apply, onApply receives the new filter definition, which you can pass to the filters prop of a chart.

import { useState } from "react";
import { AttributeFilterButton } from "@gooddata/sdk-ui-filters";
import { newNegativeAttributeFilter } from "@gooddata/sdk-model";

import "@gooddata/sdk-ui-filters/styles/css/main.css";

import * as Md from "./catalog.js";

const defaultFilter = newNegativeAttributeFilter(Md.EmployeeName.Default, []);

export const AttributeFilterButtonExample = () => {
    const [filter, setFilter] = useState(defaultFilter);

    return (
        <AttributeFilterButton
            filter={filter}
            onApply={(updatedFilter) => {
                console.log("Applying updated filter:", updatedFilter);
                setFilter(updatedFilter);
            }}
        />
    );
};

AttributeFilterButton works the same way as AttributeFilter. The differences:

The button shows the attribute name and the current selection.
attributeFilterMode sets the filter to active, readonly, or hidden.
AttributeFilterButton has no disabled prop. Use attributeFilterMode="readonly" instead.

Default selection

To select values by default, include them in the filter prop.

<AttributeFilterButton
    filter={newPositiveAttributeFilter(Md.EmployeeName.Default, ["Abbie Adams"])}
    onApply={setFilter}
/>

Hidden and static elements

hiddenElements removes elements from the list and from the resulting filter. Give the items in the same form as the filter elements: values for a value-based filter. Make sure your input filter is consistent with them: a positive filter must not contain any hidden element, and a negative filter must contain all of them.
staticElements shows a fixed list of elements instead of loading them from the backend.

Parent-child relationships between filters

To make one attribute filter depend on another, pass parentFilters and parentFilterOverAttribute to the child filter.

parentFilterOverAttribute defines how the parent and child filters are connected. Reference an attribute of the parent filter, or an attribute that both filters share.

The parent filter can be an attribute filter definition or a visualization definition placeholder.

<div>
    <AttributeFilterButton filter={parentFilter} onApply={setParentFilter} />
    <AttributeFilterButton
        filter={filter}
        parentFilters={parentFilter ? [parentFilter] : []}
        parentFilterOverAttribute={idRef("attr.restaurantlocation.locationid")}
        onApply={setFilter}
    />
</div>

<div>
    <AttributeFilterButton connectToPlaceholder={parentFilterPlaceholder} />
    <AttributeFilterButton
        connectToPlaceholder={filterPlaceholder}
        parentFilters={parentFilterPlaceholder ? [parentFilterPlaceholder] : []}
        parentFilterOverAttribute={idRef("attr.restaurantlocation.locationid")}
    />
</div>

Multiple parent filters

<AttributeFilterButton
    filter={childFilter}
    parentFilters={[parentFilter1, parentFilter2]}
    parentFilterOverAttribute={idRef("attr.common.connectionid")}
    onApply={setChildFilter}
/>

Connecting attribute per parent filter

parentFilterOverAttribute can also be a function. It’s called for every parent filter and returns the connecting attribute for it.

<AttributeFilterButton
    filter={childFilter}
    parentFilters={[parentFilter]}
    parentFilterOverAttribute={(parentFilter) => {
        // Return different connection attributes based on parent filter
        if (isRegionFilter(parentFilter)) {
            return idRef("attr.region.id");
        }
        return idRef("attr.country.id");
    }}
    onApply={setChildFilter}
/>

Dependent date filters

You can make an attribute filter depend on date filters (beta). The attribute filter then shows only the elements that are relevant for the specified date range. The dependentDateFilters prop takes dashboard date filters (IDashboardDateFilter), not the IDateFilter objects you pass to visualizations.

import { idRef, type IDashboardDateFilter } from "@gooddata/sdk-model";

// Last 6 months including the current one
const dateFilter: IDashboardDateFilter = {
    dateFilter: {
        type: "relative",
        granularity: "GDC.time.month",
        from: -5,
        to: 0,
        dataSet: idRef("date.dataset", "dataSet"),
    },
};

<AttributeFilterButton
    filter={attributeFilter}
    dependentDateFilters={[dateFilter]}
    onApply={setAttributeFilter}
/>;

Single value selection

To let users select only one value at a time, set selectionMode to "single".

import { useState } from "react";
import { AttributeFilterButton } from "@gooddata/sdk-ui-filters";
import { newPositiveAttributeFilter } from "@gooddata/sdk-model";

import "@gooddata/sdk-ui-filters/styles/css/main.css";
import * as Md from "./catalog.js";

const singleValueFilter = newPositiveAttributeFilter(Md.Region.Default, []);

export const SingleSelectionExample = () => {
    const [filter, setFilter] = useState(singleValueFilter);

    return (
        <AttributeFilterButton
            filter={filter}
            selectionMode="single"
            selectFirst={true} // Automatically select first available element
            onApply={(updatedFilter) => {
                console.log("Single selection applied:", updatedFilter);
                setFilter(updatedFilter);
            }}
        />
    );
};

In single selection mode:

The filter must be a positive filter with at most one selected element.
The dropdown closes after a user selects a value.
selectFirst selects the first available element when the filter is empty.

Filter the list by measures, facts, or attributes

To list only the elements that are compatible with specific measures, facts, or attributes, pass their object references (ObjRef) in validateElementsBy. For example, list only products that have sales, or only regions with active customers.

import { useState } from "react";
import { AttributeFilterButton } from "@gooddata/sdk-ui-filters";
import { attributeDisplayFormRef, idRef, newNegativeAttributeFilter } from "@gooddata/sdk-model";

import "@gooddata/sdk-ui-filters/styles/css/main.css";
import * as Md from "./catalog.js";

const defaultFilter = newNegativeAttributeFilter(Md.Product.Name, []);

export const ValidatedFilterExample = () => {
    const [filter, setFilter] = useState(defaultFilter);

    return (
        <AttributeFilterButton
            filter={filter}
            validateElementsBy={[
                idRef("revenue", "measure"), // Measure
                attributeDisplayFormRef(Md.Product.Category), // Attribute label
                idRef("fact.sales.amount", "fact"), // Fact
            ]}
            onApply={setFilter}
        />
    );
};

Backend support

Element validation needs the supportsAttributeFilterElementsLimiting backend capability. Backends without it ignore validateElementsBy.

Customizing AttributeFilterButton components

Beta

AttributeFilterButton component customizations are in beta.

To change the look of AttributeFilterButton, pass your own components for specific parts of it.

<AttributeFilterButton
    filter={newNegativeAttributeFilter(Md.EmployeeName.Default, [])}
    onApply={setFilter}
    // Your own component for the "Apply" and "Cancel" buttons
    DropdownActionsComponent={CustomActions}
    // Your own component for each attribute element
    ElementsSelectItemComponent={CustomItem}
/>

If the props passed to a custom component aren’t enough, call the useAttributeFilterContext hook inside it to read the full internal state of the filter.

const { attribute } = useAttributeFilterContext();

Use customizations for small changes to the AttributeFilterButton UI. For a UI that differs a lot, build your own with the useAttributeFilterController hook.

The *Component props and the parts of the UI they replace are the same as for AttributeFilter, see Customizable parts. Only the dropdown button looks different:

Props

AttributeFilterButton takes the props below except disabled, plus attributeFilterMode (VisibilityMode: "active", "readonly", or "hidden").

Prop	Type	Required	Description	Inherited from
`alignPoints`	`IAlignPoint[]`	No	Specifies the align points for the attribute filter dropdown body. In other words where the dropdown body should be placed.	`IAttributeFilterCoreProps`
`backend`	`IAnalyticalBackend`	No	Specify an instance of analytical backend instance to work with.	`IAttributeFilterCoreProps`
`connectToPlaceholder`	`IPlaceholder<IAttributeFilter>`	No	Specify @gooddata/sdk-ui#IPlaceholder to use to get and set the value of the attribute filter.	`IAttributeFilterCoreProps`
`customIcon`	`IFilterButtonCustomIcon`	No	(Alpha) Represents a custom icon along with a tooltip.	`IAttributeFilterCoreProps`
`dependentDateFilters`	`IDashboardDateFilter[]`	No	(Beta) Specifies a dependent date filter that will be used to reduce options for for current attribute filter.	`IAttributeFilterCoreProps`
`disabled`	`boolean`	No	(Alpha) Specifies the visibility mode of the filter.	`IAttributeFilterCoreProps`
`displayAsLabel`	`ObjRef`	No	(Alpha) Provide a attribute filter label used for representing elements in component. Used only for filter with elements selection. For text filters (arbitrary, match) it is not used.	`IAttributeFilterCoreProps`
`DropdownActionsComponent`	`ComponentType<IAttributeFilterDropdownActionsProps>`	No	(Beta) Customize attribute filter dropdown actions component.	`IAttributeFilterCustomComponentProps`
`DropdownBodyComponent`	`ComponentType<IAttributeFilterDropdownBodyProps>`	No	(Beta) Customize attribute filter dropdown body component.	`IAttributeFilterCustomComponentProps`
`DropdownButtonComponent`	`ComponentType<IAttributeFilterDropdownButtonProps>`	No	(Beta) Customize attribute filter dropdown button component.	`IAttributeFilterCustomComponentProps`
`ElementsSearchBarComponent`	`ComponentType<IAttributeFilterElementsSearchBarProps>`	No	(Beta) Customize attribute filter search bar component.	`IAttributeFilterCustomComponentProps`
`ElementsSelectActionsComponent`	`ComponentType<IAttributeFilterElementsActionsProps>`	No	(Beta) Customize attribute filter elements select action component (Select all checkbox)	`IAttributeFilterCustomComponentProps`
`ElementsSelectComponent`	`ComponentType<IAttributeFilterElementsSelectProps>`	No	(Beta) Customize attribute filter elements select component.	`IAttributeFilterCustomComponentProps`
`ElementsSelectErrorComponent`	`ComponentType<IAttributeFilterElementsSelectErrorProps>`	No	(Beta) Customize attribute filter elements select error component.	`IAttributeFilterCustomComponentProps`
`ElementsSelectItemComponent`	`ComponentType<IAttributeFilterElementsSelectItemProps>`	No	(Beta) Customize attribute filter elements select item component.	`IAttributeFilterCustomComponentProps`
`ElementsSelectLoadingComponent`	`ComponentType<IAttributeFilterElementsSelectLoadingProps>`	No	(Beta) Customize attribute filter elements select loading component.	`IAttributeFilterCustomComponentProps`
`EmptyResultComponent`	`ComponentType<IAttributeFilterEmptyResultProps>`	No	(Beta) Customize attribute filter empty result component.	`IAttributeFilterCustomComponentProps`
`enableImmediateAttributeFilterDisplayAsLabelMigration`	`boolean`	No	Enables the migration of displayAsLabel to be immediately reported to the parent app.	`IAttributeFilterCoreProps`
`ErrorComponent`	`ComponentType<IAttributeFilterErrorProps>`	No	(Beta) Customize attribute filter with a component to be rendered if initialization fails.	`IAttributeFilterCustomComponentProps`
`filter`	`IAttributeFilter`	No	Specify an attribute filter that will be customized using this filter.	`IAttributeFilterCoreProps`
`FilterMenuComponent`	`ComponentType<IFilterMenuProps>`	No	(Alpha) Customize filter mode menu component.	`IAttributeFilterCustomComponentProps`
`fullscreenOnMobile`	`boolean`	No	Customize, whether the filter should take the entire screen on mobile devices.	`IAttributeFilterCoreProps`
`hiddenElements`	`string[]`	No	If specified, these will be excluded from the elements available for selection and will also be removed from the resulting filter. This effectively behaves as if those elements were not part of the underlying display form.	`IAttributeFilterCoreProps`
`hideTooltips`	`boolean`	No	(Alpha) When true, hides all help/info tooltip icons within the attribute filter.	`IAttributeFilterCoreProps`
`LoadingComponent`	`ComponentType<IAttributeFilterLoadingProps>`	No	(Beta) Customize attribute filter with a component to be rendered if attribute filter is loading. Note that this will be rendered only during the initialization of the attribute filter.	`IAttributeFilterCustomComponentProps`
`locale`	`ILocale`	No	Locale to use for localization of appearing texts.	`IAttributeFilterCoreProps`
`menuConfig`	`IAttributeFilterMenuConfig`	No	(Alpha) Configuration for the attribute filter header menu.	`IAttributeFilterCoreProps`
`onApply`	`OnApplyCallbackType`	No	Specify function which will be called when user clicks ‘Apply’ button on this filter. Note: this callback is typically not called when using Dashboard apply filters mode ALL_AT_ONCE because there is no apply button dispalyed in attribute filter component. See withoutApply prop.	`IAttributeFilterCoreProps`
`onChange`	`OnChangeCallbackType`	No	Specify function which will be called when user changes filter working selection. This is the selection that is staged for application. Not applied yet. Covers all filter modes: elements, arbitrary, match.	`IAttributeFilterCoreProps`
`onError`	`(error:` `GoodDataSdkError) => void`	No	Callback that will be triggered when error is thrown.	`IAttributeFilterCoreProps`
`onInitLoadingChanged`	`(loading: boolean, attribute?:` `IAttributeMetadataObject) => void`	No	Callback that will be triggered when initialization loading state changes.	`IAttributeFilterCoreProps`
`onSelect`	`OnSelectCallbackType`	No	(Deprecated) Specify function which will be called when user changes filter working selection.	`IAttributeFilterCoreProps`
`overlayPositionType`	`OverlayPositionType`	No	Specifies the overlay position type for the attribute filter dropdown.	`IAttributeFilterCoreProps`
`parentFilterOverAttribute`	`ParentFilterOverAttributeType`	No	Specify the over attribute - an attribute the filter and its parent filter are connected through.	`IAttributeFilterCoreProps`
`parentFilters`	`AttributeFiltersOrPlaceholders`	No	Specifies a parent attribute filter that will be used to reduce options for current attribute filter.	`IAttributeFilterCoreProps`
`selectFirst`	`boolean`	No	Specify if first available element should be automatically selected for empty selection.	`IAttributeFilterCoreProps`
`selectionMode`	`DashboardAttributeFilterSelectionMode`	No	Customize, how many elements can be selected by filter.	`IAttributeFilterCoreProps`
`showHeader`	`boolean`	No	(Alpha) When true, always show the dropdown header with title and filter mode menu, even when there is only one available filter mode.	`IAttributeFilterCoreProps`
`staticElements`	`IAttributeElement[]`	No	If specified, these elements will replace the elements that would be loaded from the server. Note that if using this, limiting measures and/or filters will not work: it is your responsibility to filter the static elements yourself.	`IAttributeFilterCoreProps`
`StatusBarComponent`	`ComponentType<IAttributeFilterStatusBarProps>`	No	(Beta) Customize attribute filter status bar component.	`IAttributeFilterCustomComponentProps`
`TextFilterBodyComponent`	`ComponentType<ITextFilterBodyProps>`	No	(Alpha) Customize text filter body component.	`IAttributeFilterCustomComponentProps`
`title`	`string`	No	Specify title for the attribute filter.	`IAttributeFilterCoreProps`
`validateElementsBy`	`ObjRef[]`	No	Specify the items that are used for elements availability validation (metrics or attributes, labels, or facts that the backend will use to build validation metrics from). Only the elements that are compatible with the provided elements will be shown in the filter.	`IAttributeFilterCoreProps`
`withoutApply`	`boolean`	No	(Alpha) This enables filter mode without apply button. If true, it is responsibility of a client, to apply filters when needed. Typically uses onChange callback to catch filter state. Note, onApply callback is not called when this is true.	`IAttributeFilterCoreProps`
`workingFilter`	`IAttributeFilter`	No	(Deprecated) (Alpha) Specify a working attribute filter that will be shown.	`IAttributeFilterCoreProps`
`workspace`	`string`	No	Specify workspace to work with.	`IAttributeFilterCoreProps`

Attribute filter button

Structure

Example