- Data Grid docs
- Developers
Assistant
Let users describe a view in their own words, have your own service turn the words into a view state, and apply it once the grid has checked it against the fields.
"Revenue by region for 2026, largest first" is quicker to say than to set up with three dialogs. The assistant option adds Ask to the toolbar: the user writes what they want to see, your function turns the words into a view state, and the grid applies it once it has checked it. The grid never calls an AI service itself. Your function decides how the words are understood, typically by asking a language model through your own server, which keeps the API key and your rules about what may be sent.
In the grid
- Choose Ask in the toolbar and write the view you want, such as "orders over 1,000 in the East, newest first".
- Ask sends it. While your function works, the dialog says "Thinking…".
- When the answer holds a state, the grid checks it and applies it: filters, sort, groups, columns, totals and any other keys it sets. The dialog closes, or shows the answer's message when there is one.
- An answer the grid can't apply leaves the view as it was and shows what was wrong, for example a field that doesn't exist.
From code
| Option or method | Does |
|---|---|
assistant: (request) => Promise<{ state?, message? }> | Adds Ask to the toolbar and answers each prompt |
askAssistant(prompt) | Sends a prompt to assistant and applies the checked answer, as Ask does; resolves with { state, message } |
getStateSchema() | A JSON Schema of the view state with this grid's field names spelled out |
validateState(state) | The problems of a state, or some keys of one, against the fields: unknown keys, fields and conditions; empty when it is sound |
openDialog('assistant') | Opens the Ask dialog |
The request your function gets:
| Property | Holds |
|---|---|
prompt | What the user wrote |
state | The current view state |
fields | { name, caption, type, format } of each field |
schema | The JSON Schema of the state keys an answer may set, the same as getStateSchema() |
language | The interface language, such as 'en' or 'de', so the answer's message can match it |
The request holds no records: only the field names and types, the current view and the user's words. What your function sends further is up to you.
The answer is { state, message }, both optional. state holds some keys of TableState; the keys it leaves out keep their values (except collapsed: every group opens unless the answer says otherwise), and the columns it leaves out of columns keep their settings, after the ones it names. A state with a tree clears the groups. message is shown to the user, for example to explain the view or to ask for a clearer request. An answer with a message and no state changes nothing.
The check is strict: every key, field name and condition must be one the grid knows, or nothing applies. askAssistant then rejects with the problems, and Ask shows them.
JavaScript
import { mountTable } from '@8sheets/data-grid';
const grid = await mountTable(document.querySelector('#orders'), {
title: 'Orders',
data: orders,
// Your server talks to the language model; the page never holds its key.
assistant: async ({ prompt, state, schema, language }) => {
const res = await fetch('/api/grid-assistant', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ prompt, state, schema, language }),
});
if (!res.ok) return { message: 'The assistant is unavailable right now.' };
return res.json(); // { state?, message? }
},
});
// The same from your own search box.
const { message } = await grid.askAssistant('revenue by region, largest first');React
import { useMemo } from 'react';
import { DataGrid } from '@8sheets/data-grid-react';
import { askGridAssistant } from './grid-assistant.js'; // the fetch from the JavaScript tab
export function Orders({ orders }) {
const options = useMemo(() => ({ title: 'Orders', data: orders, assistant: askGridAssistant }), [orders]);
return <div style={{ height: 480 }}><DataGrid options={options} /></div>;
}Vue
<script setup>
import { computed } from 'vue';
import { DataGrid } from '@8sheets/data-grid-vue';
import { askGridAssistant } from './grid-assistant.js'; // the fetch from the JavaScript tab
const props = defineProps({ orders: Array });
const options = computed(() => ({ title: 'Orders', data: props.orders, assistant: askGridAssistant }));
</script>
<template>
<div style="height: 480px"><DataGrid :options="options" /></div>
</template>Angular
import { Component, Input, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';
import { DataGridComponent, DataGridOptions } from '@8sheets/data-grid-angular';
@Component({
selector: 'app-orders',
imports: [DataGridComponent],
template: `<eight-data-grid [options]="options" style="height: 480px" />`,
})
export class Orders {
private http = inject(HttpClient);
options: DataGridOptions = {};
@Input() set orders(data: Record<string, unknown>[]) {
this.options = {
title: 'Orders',
data,
assistant: ({ prompt, state, schema, language }) =>
firstValueFrom(this.http.post<any>('/api/grid-assistant', { prompt, state, schema, language })),
};
}
}The endpoint on your server
/api/grid-assistant is yours to write, in any language. It should:
- Check that the user may ask, and limit how often.
- Ask a language model for one JSON object that matches
schema: give it the user'sprompt, the currentstateand the schema, and tell it to answer with the state keys that make the view the user asked for, plus a shortmessagewhen it needs to explain something. - Parse the model's answer and return
{ state, message }as JSON. The grid checks the state before it applies anything, so a wrong answer can't break the view; it only shows the problems.
Most model APIs can be told to answer with JSON that follows a schema; pass schema there. The field names in it are the grid's, which steers the model towards real columns, and the grid's own check refuses any it invents.
getStateSchema() and validateState() work without the assistant option too, for states from any outside source: a link a user shared, a view stored by an older version of your app.
const problems = grid.validateState(JSON.parse(atob(location.hash.slice(1))));
if (problems.length) console.warn('The shared view does not fit:', problems);
Limits
- The assistant sets the view: filters, sort, groups, columns, totals, a tree and the other state keys. It doesn't edit, add or remove records.
- How well it understands depends on your function and the model behind it; the grid only guarantees that a state it applies is sound.
- An answer is applied as a whole or not at all.