ag-grid-react-components/dist/llms.txt

Give your users the date filtering they deserve. Relative date queries, quick filters, and shareable views for AG Grid.

# AG Grid React Components

> Modular, tree-shakeable date filtering components for AG Grid with minimal bundle size

## Overview

This project provides advanced date filtering components for AG Grid React applications with a modular architecture designed for minimal bundle size. Start with just 25KB for basic features or add advanced capabilities as needed.

## Bundle Sizes

| Use Case | Bundle Size |
|----------|-------------|
| Just DateFilter (native) | 25KB |
| With React DatePicker | 65KB |
| All components | 85KB |

## Modular Architecture

### Core Package Features
All components in a single tree-shakeable package:
- DateFilter with native HTML5 inputs (25KB minimal)
- QuickFilterDropdown for preset filters
- ActiveFilters display component
- URL state persistence with automatic compression
- Optional React DatePicker integration (+40KB when used)
- Optional styles and themes


## Components

### DateFilter
A modular date filter that supports both absolute dates and relative expressions.

**Features:**
- Native HTML5 date inputs by default (zero dependencies)
- Optional React DatePicker via adapter pattern
- Relative expressions: Today, Today-7d, StartOfMonth, etc.
- All standard filter operations
- Open-ended date ranges
- Configurable inclusive/exclusive boundaries

**Usage:**
```typescript
// Minimal (25KB total)
import { createDateFilter } from 'ag-grid-react-components';
const DateFilter = createDateFilter();

// With React DatePicker (65KB total)
import { createDateFilter, reactDatePickerAdapter } from 'ag-grid-react-components';
const DateFilter = createDateFilter({
  datePickerAdapter: reactDatePickerAdapter
});

// Column definition
{
  field: 'date',
  filter: DateFilter,
  floatingFilter: true,
  filterParams: {
    afterInclusive: true,
    beforeInclusive: true,
    rangeInclusive: { from: true, to: true }
  }
}
```

**Open-Ended Ranges:**
```typescript
// Filter all dates after Jan 1, 2024
api.setFilterModel({
  dateColumn: {
    type: "inRange",
    mode: "absolute",
    dateFrom: new Date("2024-01-01"),
    dateTo: null  // No end date
  }
});

// Filter all dates before today
api.setFilterModel({
  dateColumn: {
    type: "inRange",
    mode: "relative",
    expressionFrom: null,  // No start date
    expressionTo: "Today"
  }
});
```

### QuickFilterDropdown
A lightweight dropdown for applying predefined filters.

**Features:**
- Zero dependencies
- Works with any column type
- Portal rendering for constrained containers
- Keyboard navigation
- Tree-shakeable

**Usage:**
```typescript
import { createQuickFilterDropdown } from 'ag-grid-react-components';
const QuickFilterDropdown = createQuickFilterDropdown();

<QuickFilterDropdown
  api={gridApi}
  columnId="date"
  options={filterOptions}
  placeholder="Select filter"
  usePortal="never" // or "always" for constrained containers
/>
```

### ActiveFilters
Display active filters as removable pills.

**Features:**
- Zero dependencies
- Minimal DOM footprint
- TypeScript interfaces for type safety
- CSS Module isolation

**Usage:**
```typescript
import { createActiveFilters } from 'ag-grid-react-components';
const ActiveFilters = createActiveFilters();

<ActiveFilters
  api={gridApi}
  filterModel={filterModel}
  className="custom-class"
/>
```

### URL State Persistence
Comprehensive grid state persistence with URL synchronization and compression.

**Features:**
- **Full Grid State**: Persists filters, columns, sorting, and grouping
- **URL Compression**: Uses LZ-String for 50-90% smaller URLs
- **Browser History**: Full back/forward navigation support
- **Shareable Links**: Share complete grid configurations
- **Selective Persistence**: Choose which state to include
- **TypeScript Support**: Full type safety with GridState and GridStateOptions

**Basic Usage:**
```typescript
import { setupGridStatePersistence } from 'ag-grid-react-components';

// Full grid state with compression
const cleanup = setupGridStatePersistence(gridApi, {
  useCompression: true,
  maxUrlLength: 2000,
  onStateLoad: (state) => console.log('Loaded:', state),
  onStateSave: (state) => console.log('Saved:', state)
});
```

**Advanced Usage:**
```typescript
import { captureGridState, applyGridState } from 'ag-grid-react-components';

// Manual state capture
const state = captureGridState(gridApi, {
  includeFilters: true,
  includeColumns: true,
  includeSort: true,
  includeRowGrouping: false
});

// Save to localStorage
localStorage.setItem('gridState', JSON.stringify(state));

// Restore state
const savedState = JSON.parse(localStorage.getItem('gridState'));
applyGridState(gridApi, savedState);
```

**Compression Effectiveness:**
- Simple filters: ~72% reduction
- Complex grid state: ~88% reduction
- Repetitive data compresses best

**Migration from Legacy:**
```typescript
// Old (filters only)
setupFilterStatePersistence(params.api);

// New (full state)
setupGridStatePersistence(params.api, {
  useCompression: true,
  includeFilters: true,
  includeColumns: true,
  includeSort: true
});
```

## Date Expression Syntax

Pattern: `[Anchor][Operator][Value][Unit]`

**Anchors:**
- Today - Current date at midnight
- Now - Current date and time
- StartOfWeek - Monday
- EndOfWeek - Sunday
- StartOfMonth - First day of month
- EndOfMonth - Last day of month
- StartOfYear - January 1st
- EndOfYear - December 31st

**Units:**
- d - days (Today-7d)
- w - weeks (Today+2w)
- M - months (StartOfMonth-1M)
- y - years (StartOfYear+1y)
- h - hours (Now-3h)
- m - minutes (Now+30m)

## Installation

```bash
npm install ag-grid-react-components

# Peer dependencies
npm install ag-grid-community ag-grid-react ag-grid-enterprise date-fns
```

## Requirements

- React 18+
- AG Grid 33.3.0+
- AG Grid Enterprise (for filter components)
- date-fns 4+

## License

MIT License - Free for commercial and non-commercial use.

## Links

- GitHub: https://github.com/ryanrozich/ag-grid-react-components
- NPM: https://www.npmjs.com/package/ag-grid-react-components
- Demo: https://demo.rozich.net/ag-grid-react-components/

## Author

Created by Ryan Rozich. Not affiliated with AG Grid Ltd.