# useGridActiveFilter

[← Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)

Composable that tracks active Grid filter state by field and provides a resolver function you can bind to Grid column definitions.

## Prerequisites

- Vue 3 Composition API
- `@progress/kendo-data-query`
- `@progress/kendo-vue-grid`
- `@featherk/composables`

Install:

```bash
npm install @featherk/composables
```

## Compatibility

- Built and tested with Kendo UI for Vue Grid v6.4.1.

## Import

`useGridActiveFilter` is exported from the grid feature barrel:

```ts
import { useGridActiveFilter } from "@featherk/composables/grid";
```

## Quick Start

```ts
import { computed, ref } from "vue";
import type { CompositeFilterDescriptor } from "@progress/kendo-data-query";
import type { GridFilterChangeEvent, GridColumnProps } from "@progress/kendo-vue-grid";
import { useGridActiveFilter } from "@featherk/composables/grid";

const filter = ref<CompositeFilterDescriptor | undefined>(undefined);

const activeClass = useGridActiveFilter(filter);

const columns = computed<GridColumnProps[]>(() => [
  {
    field: "ProductName",
    title: "Product Name",
    filterable: true,
    headerClassName: activeClass("ProductName"),
  },
  {
    field: "Category",
    title: "Category",
    filterable: true,
    headerClassName: activeClass("Category"),
  },
]);

const filterChange = (event: GridFilterChangeEvent) => {
  filter.value = event.filter;
};
```

Template bindings (essentials shown):

```html
<Grid
  :columns="columns"
  :filter="filter"
  @filterchange="filterChange" />
```

## API

### `useGridActiveFilter(filterRef: Ref<CompositeFilterDescriptor | undefined>)`

Returns a resolver function for generating field-based class flags.

- **Returns** `(field: string) => "active" | ""`
  - Call the returned function inside a `computed` with the column's field name.
  - Returns `"active"` when a filter exists for that field, or `""` when it does not.
  - Vue tracks the `filterRef` dependency automatically — no manual update call is needed.

## Behavior Notes

- Handles nested filter groups recursively.
- Ignores malformed/unknown filter nodes safely.
- If `filterRef` is `undefined` or has no filters, all fields resolve to `""`.

## Typical Usage Pattern

1. Keep a single `filter` ref that is passed to the Grid and to `useGridActiveFilter`.
2. Call `useGridActiveFilter(filter)` once to get the `activeClass` resolver.
3. Inside a `computed` column definition, bind `activeClass("fieldName")` to each filterable column's `headerClassName`.
4. In `@filterchange`, set `filter.value = event.filter` — Vue reactivity handles the rest.

## Styling

The composable only provides class state and does not ship CSS.

Example:

```css
.k-grid .k-header.active {
  font-weight: 600;
  text-decoration: underline;
}
```