- Data Grid docs
- Working with records
Search and filters
Narrow the records with the search box, a filter builder of conditions and groups, and the filter row, and find cells with Find, from the toolbar or through the view state.
Search, filters and the filter row narrow the records to the ones that match. All three combine: a record shows when it matches the search and every filter. They always cover the whole result, not just the rows on screen, and a server source receives them in the view state. Find is the other way round: it leaves the records as they are and moves from one cell holding a text to the next.
Open the filters example: an "any" group with an "all" group inside it, and Find · the large example: filter row over 1,000,000 records
In the grid
- Search looks for the text in every visible column, ignoring case. It applies as you type.
- Filter (in the toolbar or a column's menu) opens the filter builder. Each line is a condition on a field; the list of conditions fits the field's type (see Conditions). Match all conditions keeps a record that meets every line, Match any condition one that meets at least one. Add group adds a group of conditions with a join of its own, so one filter can say "Region is East, or Revenue is over 1,000 and Units under 5".
- For local data, Pick values lists a column's distinct values with their counts, with a search box to find one in a long list.
- Filter row puts an input under each heading. What you type applies 300 ms after you stop typing.
- Each filter shows as a chip above the grid; remove one with its chip, or all of them with Clear all. Conditions joined by "all" become a chip each; an "any" join or a group shows as one chip.
- Find in the toolbar, or Ctrl+F (⌘F on a Mac) while focus is in the records, opens a bar under the toolbar; see Find.
Filter row syntax
| Type | Means |
|---|---|
>100, >=5, <0, <=9 | Greater than, at least, less than, at most (number and date columns) |
=42, <>3 | Equal, not equal |
10..20 | Between 10 and 20, both included |
2,5 | A decimal comma works too: 2.5 |
east | Text columns: contains "east", ignoring case |
=East | Text columns: exactly "East", ignoring case |
Clearing an input removes its filter.
From code
| Method | Does |
|---|---|
setSearch(text) | Searches every visible field; '' clears it |
setFilters(filters), addFilter(filter) | Replaces the filters, or adds one; entries combine with AND, and an { any } or { all } group is one entry |
clearFilters(field?) | Removes every filter, or one field's; the search stays |
setQuickFilter(field, text) | Sets a field's filter-row filter from typed text such as '>30'; '' removes it |
setFilterRow(on) | Shows or hides the filter row; its filters stay either way |
getDistinctValues(field, { limit }) | A field's values with their counts, among the records the other filters let through (local records) |
In the state, the search is search, the filters are filters and the filter row is filterRow. Each entry of filters is a TableFilterEntry: a condition { field, op, value, value2, values, percent } (filter-row ones carry quick: true and the typed text), or a group { any: [...] } that keeps a record meeting one of its parts, or { all: [...] } that keeps one meeting every part. Groups nest. Every change fires stateChange with the keys that changed.
JavaScript
import { mountTable } from '@8sheets/data-grid';
const grid = await mountTable(document.querySelector('#orders'), {
title: 'Orders',
data: orders,
onStateChange: (e) => {
if (e.changed.includes('filters') || e.changed.includes('search')) badge.textContent = grid.getCounts().matches;
},
});
// East and West orders above 1,000, with the filter row open.
await grid.setFilters([
{ field: 'Region', op: 'in', values: ['East', 'West'] },
{ field: 'Revenue', op: 'gt', value: 1000 },
]);
await grid.setFilterRow(true);
await grid.setQuickFilter('Units', '10..20');
// East, or big orders of few units: a group with its own join.
await grid.setFilters([
{ any: [
{ field: 'Region', op: 'equal', value: 'East' },
{ all: [{ field: 'Revenue', op: 'gt', value: 1000 }, { field: 'Units', op: 'lt', value: 5 }] },
] },
]);
// Your own search box and region list.
find.addEventListener('input', (e) => grid.setSearch(e.target.value));
for (const { value, count } of await grid.getDistinctValues('Region')) regions.add(new Option(`${value} (${count})`, value));React
import { useRef, useState } from 'react';
import { DataGrid } from '@8sheets/data-grid-react';
export function Orders({ options }) {
const ref = useRef(null);
const [matches, setMatches] = useState(null);
return (
<>
<input placeholder="Find" onChange={(e) => ref.current.setSearch(e.target.value)} />
<button onClick={() => ref.current.setFilters([{ field: 'Revenue', op: 'gt', value: 1000 }])}>Big orders</button>
<button onClick={() => ref.current.clearFilters()}>All orders</button>
<span>{matches ?? '…'} orders</span>
<div style={{ height: 480 }}>
<DataGrid ref={ref} options={options} onStateChange={() => setMatches(ref.current.getCounts().matches)} />
</div>
</>
);
}Vue
<script setup>
import { ref } from 'vue';
import { DataGrid } from '@8sheets/data-grid-vue';
defineProps({ options: Object });
const dataGrid = ref(null);
const matches = ref(null);
</script>
<template>
<input placeholder="Find" @input="(e) => dataGrid.setSearch(e.target.value)" />
<button @click="dataGrid.setFilters([{ field: 'Revenue', op: 'gt', value: 1000 }])">Big orders</button>
<button @click="dataGrid.clearFilters()">All orders</button>
<span>{{ matches ?? '…' }} orders</span>
<div style="height: 480px">
<DataGrid ref="dataGrid" :options="options" @state-change="matches = dataGrid.getCounts().matches" />
</div>
</template>Angular
import { Component, Input, ViewChild } from '@angular/core';
import { DataGridComponent, DataGridOptions } from '@8sheets/data-grid-angular';
@Component({
selector: 'app-orders',
imports: [DataGridComponent],
template: `
<input placeholder="Find" (input)="grid.setSearch($any($event.target).value)" />
<button (click)="grid.setFilters([{ field: 'Revenue', op: 'gt', value: 1000 }])">Big orders</button>
<button (click)="grid.clearFilters()">All orders</button>
<span>{{ matches ?? '…' }} orders</span>
<eight-data-grid #grid [options]="options" (stateChange)="matches = grid.getCounts().matches" style="height: 480px" />`,
})
export class Orders {
@Input() options: DataGridOptions = {};
@ViewChild('grid') grid!: DataGridComponent;
matches: number | null = null;
}Conditions
op | Value |
|---|---|
equal, notEqual, gt, gte, lt, lte | value |
between, notBetween | value and value2 |
contains, notContains, beginsWith, endsWith | value, text, ignoring case |
blank, notBlank | none |
in, notIn | values, a list |
top, bottom | value, the number of records, or a percentage of them with percent: true |
aboveAverage, belowAverage | none |
today, yesterday, tomorrow, thisWeek, thisMonth, lastMonth, thisYear, lastYear | none, for date columns |
The filter builder offers the conditions that fit each field: the text conditions for text fields; the comparisons, between and not between for numbers and dates; top, bottom and the averages for numbers; the periods for dates; and blank or not blank for all of them. in and notIn come from Pick values, and percent from code. Locally and in tableQueryService every condition and group works; a server of your own decides which it supports.
await grid.addFilter({ field: 'Revenue', op: 'top', value: 10, percent: true }); // the top 10 % by revenue
await grid.addFilter({ field: 'Date', op: 'lastMonth' });
Find
Find looks for a text in the cells of the visible columns, ignoring case, across every matching record, not only the drawn ones. It doesn't hide any record: the cells that hold the text are highlighted, Enter moves to the next one and Shift+Enter to the previous one, wrapping at the end, and the bar shows where you are, as in "3 / 120". Escape closes the bar.
| Method | Does |
|---|---|
openFind(text?) | Opens the Find bar, with text in it |
findNext(text?, { back }) | Moves to the next cell holding text (the previous one with back: true) and focuses it; resolves with { id, field }, or null when no cell holds it |
closeFind() | Closes the bar |
const hit = await grid.findNext('Acme');
if (hit) console.log('found in', hit.field, 'of record', hit.id);
Limits
- Search looks at visible columns only; a hidden column doesn't match.
- Entries of
filterscombine with AND; for OR, put the conditions in an{ any: [...] }group, or useinfor a list of values of one column. - Pick values and Find need local data; a server source gets the other conditions, and its users narrow the records with search instead of Find.
- Find looks at the display text of visible columns, as search does.