Filter Header

Module Extensions

ColumnRegular (Extended from @revolist/revogrid)

interface ColumnRegular {
  /**
       * Hide filter input in the header
       */
      hideFilterHeader?: boolean;
  /**
       * Hide per-value row counts from the filter header selection tooltip.
       * The selected-value count badge remains visible.
       */
      hideFilterHeaderCount?: boolean;
  /**
       * Filter placeholder
       */
      filterPlaceholder?: string;
  /**
       * Custom template for popup-style header filter trigger content.
       */
      filterHeaderTemplate?: FilterHeaderTemplateFunc
}

Plugin API

FilterHeaderPresentation

Plain-text state retained by the grid-owned accessible trigger shell.

interface FilterHeaderPresentation {
  active: boolean;
  summary: string;
  details?: string
}

---

FilterHeaderTemplateFunc

Renders non-interactive content inside the grid-owned filter button. Return undefined to use the standard accessible text/count fallback.

/**
 * Renders non-interactive content inside the grid-owned filter button.
 * Return `undefined` to use the standard accessible text/count fallback.
 */
export type FilterHeaderTemplateFunc = (
  h: HyperFunc<any>,
  props: FilterHeaderTemplateProps,
) => VNodeResponse;

---

FilterHeaderTemplateProps

Shared visual-template contract for every popup-style filter header.

/** Shared visual-template contract for every popup-style filter header. */
export type FilterHeaderTemplateProps = {
  column: ColumnRegular;
  columnProp: ColumnProp;
  conditions: readonly Readonly<FilterData>[];
  presentation: FilterHeaderPresentation;
  /** @deprecated Use `presentation.active`. */
  active: boolean;
  /** @deprecated Use `presentation.summary`. */
  text: string;
  /** Selection-only compatibility data. */
  values: FilterHeaderTemplateValue[];
  /** Selection-only compatibility data. */
  totalCount?: number;
  /** Selection-only compatibility option. */
  showCount: boolean;
};

---

FilterHeaderTemplateValue

export type FilterHeaderTemplateValue = {
  value: string;
  label: string;
  count: number;
};

---

FilterHeaderTriggerState (Extended from index.ts)

export type FilterHeaderTriggerState = Omit<
  FilterHeaderTemplateProps,
  'column' | 'columnProp' | 'conditions' | 'presentation'
> & {
  conditions?: FilterHeaderTemplateProps['conditions'];
  presentation?: FilterHeaderPresentation;
};

---

FilterHeaderPlugin

The FilterHeaderPlugin enhances RevoGrid by adding interactive filter input elements to column headers, allowing users to filter grid data directly from the header. It dynamically integrates with existing column templates, providing a seamless UI for text-based filters and selection-based filters.

Key Features:

• Adds input fields below each column header for applying text-based filters.
• Integrates with the AdvanceFilterPlugin to handle complex filtering operations, supporting multiple filter types like selection and slider filters.
• Automatically wraps existing header templates to include filter inputs, maintaining existing header content alongside new filter functionality.
• Utilizes debouncing to optimize input handling, minimizing performance impact from frequent user interactions.

Usage:

• Include this plugin in RevoGrid’s plugin array to activate header filtering capabilities. AdvanceFilterPlugin is installed automatically.
• Customize column definitions to specify filter types using the filter property.

Events:

• Listens for BEFORE_HEADER_RENDER_EVENT to modify header templates and append filter UI components.

Usage Example:

import { FilterHeaderPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [FilterHeaderPlugin];

grid.columns = [
  {
    prop: 'name',
    name: 'Name',
    filter: ['input'],
  },
];

By integrating this plugin, RevoGrid provides an enhanced user experience with improved data filtering capabilities directly accessible from the grid interface.

Dependencies

• Auto-installed AdvanceFilterPlugin: Provides the advanced filtering runtime used by filter header controls.

class FilterHeaderPlugin {
  destroy();
}

---

resolveFilterHeaderLabel

export function resolveFilterHeaderLabel(captions: CaptionSource, column?: ColumnRegular): string;

---

resolveFilterHeaderPlaceholder

export function resolveFilterHeaderPlaceholder(
  captions: CaptionSource,
  kind: FilterHeaderPlaceholderKind,
): string;

---

resolveFilterHeaderSelectionSummary

export function resolveFilterHeaderSelectionSummary(
  captions: CaptionSource,
  selected: number,
  total: number,
  details?: string,
): string;

---

formatFilterHeaderAccessibleSummary

export function formatFilterHeaderAccessibleSummary(label: string, summary: string): string;

---

formatFilterHeaderValueCount

export function formatFilterHeaderValueCount(label: string, count: number): string;

---

resolveFilterHeaderAll

export function resolveFilterHeaderAll(captions: CaptionSource): string;

---

FILTER_HEADER_LOCALIZATION

Stable localization keys and English fallbacks for filter-header rendering.

FILTER_HEADER_LOCALIZATION: Readonly<{ captions: Readonly<{ filterHeaderLabel: "Filter {column}"; filterHeaderSearch: "Search…"; filterHeaderAnyDate: "Any date"; filterHeaderEither: "Either"; filterHeaderAnyItem: "Any item"; filterHeaderAnyValue: "Any value"; filterHeaderSelectionSummary: "{selected} of {total} selected"; filterHeaderSelectionSummaryWithDetails: "{selected} of {total} selected: {details}"; filterHeaderAccessibleSummary: "{label}. {summary}"; filterHeaderValueCount: "{label} ({count})"; selectionAll: "All"; }>; }>;

---

FilterHeaderPlaceholderKind

export type FilterHeaderPlaceholderKind = 'search' | 'date' | 'boolean' | 'array' | 'value';

---

renderFilterHeaderView

export function renderFilterHeaderView({
  column,
  columnProp,
  defaultNode,
  isPopupFilter,
  isInputEnabled,
  inputValue,
  showFilterCount,
  inlineControl,
  popupFilterState,
  popupFilterTemplate,
  filterLabel,
  filterPlaceholder,
  formatSelectionSummary,
  onInput,
  onPopup,
}: FilterHeaderViewOptions);

---

renderFilterHeaderTriggerContent

export function renderFilterHeaderTriggerContent(
  column: ColumnRegular | undefined,
  columnProp: ColumnProp,
  state: FilterHeaderTriggerState,
  typeTemplate?: FilterHeaderTemplateFunc,
);

---

FilterHeaderViewOptions

export type FilterHeaderViewOptions = {
  column?: ColumnRegular;
  columnProp: ColumnProp;
  defaultNode?: ReturnType<ColumnTemplateFunc>;
  isPopupFilter: boolean;
  isInputEnabled: boolean;
  inputValue: string;
  showFilterCount: boolean;
  inlineControl?: Extract<FilterHeaderControl, { kind: 'inline' }>;
  popupFilterState?: FilterHeaderTriggerState;
  popupFilterTemplate?: FilterHeaderTemplateFunc;
  filterLabel?: string;
  filterPlaceholder?: string;
  formatSelectionSummary?: FilterHeaderSelectionSummaryFormatter;
  onInput: FilterHeaderInputHandlers;
  onPopup: FilterHeaderPopupHandlers;
};

---

isInlineTextFilterItem

export function isInlineTextFilterItem(filter: FilterData): boolean;

---

FilterHeaderControl

Filter-type-owned header presentation. The grid retains the outer layout, accessibility, popup trigger, and interaction boundary.

/**
 * Filter-type-owned header presentation. The grid retains the outer layout,
 * accessibility, popup trigger, and interaction boundary.
 */
export type FilterHeaderControl =
  | {
      readonly kind: 'popup';
      /** Optional visual content rendered inside the accessible popup trigger. */
      readonly template?: FilterHeaderTemplateFunc;
    }
  | {
      readonly kind: 'inline';
      /** Interactive control rendered inside the shared non-sorting boundary. */
      readonly template: FilterHeaderInlineTemplateFunc;
      /** Optional stable class retained for type-specific presentation. */
      readonly className?: string;
    };

---

FilterHeaderInlineTemplateFunc

Renders an interactive control inside the grid-owned filter-header boundary.

/** Renders an interactive control inside the grid-owned filter-header boundary. */
export type FilterHeaderInlineTemplateFunc = FilterHeaderTemplateFunc;