Skip to content
ToolboxJS

Getting Started

Using a framework? Jump directly to Angular, React, or Vue.

Quick Start

Section titled “Quick Start”

  1. Install the package

    Terminal window
    npm install @toolbox-web/grid

  2. Import and use

    import '@toolbox-web/grid';                       // registers <tbw-grid>
    import { queryGrid } from '@toolbox-web/grid';     // typed DOM helper

  3. Add the grid to your HTML

    <tbw-grid id="my-grid" style="height: 400px;"></tbw-grid>

Declarative Columns (No JavaScript)

Section titled “Declarative Columns (No JavaScript)”

Define columns directly in HTML — great for static layouts and quick prototyping:

<tbw-grid style="height: 400px;">
  <tbw-grid-column field="id" header="ID" type="number" sortable></tbw-grid-column>
  <tbw-grid-column field="name" header="Name"></tbw-grid-column>
  <tbw-grid-column field="email" header="Email"></tbw-grid-column>
</tbw-grid>

Set rows from JavaScript or via the rows HTML attribute (JSON). See Light DOM Columns for the full attribute reference.

Auto-Inferred Columns

Section titled “Auto-Inferred Columns”

Skip column configuration entirely — the grid creates columns from your data:

import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';


const grid = queryGrid('#my-grid');
grid.rows = [
  { id: 1, name: 'Alice Johnson', email: 'alice@example.com', active: true },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com', active: false },
];
// → Creates ID, Name, Email, and Active columns automatically

The grid detects types (number, boolean, date, string) from values and formats headers from field names (firstName → First Name). See Column Inference for details.

Framework Integration

Section titled “Framework Integration”

The grid is a standard web component that works in any JavaScript environment — you can always use the Vanilla JS approach in any framework. For React, Vue, and Angular, we also provide dedicated adapter packages that enable custom component renderers and editors.

Add a grid element to your HTML, then configure it from JavaScript:

index.html
<tbw-grid style="height: 400px;"></tbw-grid>
main.ts
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';


const grid = queryGrid('tbw-grid');


grid.columns = [
  { field: 'id', header: 'ID', type: 'number' },
  { field: 'name', header: 'Name' },
  { field: 'email', header: 'Email' },
];


grid.rows = [
  { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
  { id: 3, name: 'Carol White', email: 'carol@example.com' },
];

That’s a working grid. From here, add features as you need them — sorting, editing, selection, and more are each a one-line import:

main.ts (with features)
import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/editing';
import '@toolbox-web/grid/features/selection';
import '@toolbox-web/grid/features/filtering';


const grid = queryGrid('tbw-grid');


grid.gridConfig = {
  columns: [
    { field: 'id', header: 'ID', type: 'number' },
    { field: 'name', header: 'Name', editable: true },
    { field: 'email', header: 'Email', editable: true },
  ],
  features: {
    editing: 'dblclick',
    selection: 'row',
    filtering: true,
  },
};


grid.rows = [
  { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
  { id: 3, name: 'Carol White', email: 'carol@example.com' },
];


grid.on('cell-commit', (detail) => console.log('Edited:', detail));

See Core Features for renderers, formatters, and custom editors.

Plain JavaScript (No Build Step)

Section titled “Plain JavaScript (No Build Step)”

Don’t use TypeScript or a bundler? The grid works with a single <script> tag using the UMD bundle. Everything is available on the global TbwGrid object:

index.html
<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@toolbox-web/grid/umd/grid.umd.js"></script>
</head>
<body>
  <tbw-grid id="my-grid" style="height: 400px;"></tbw-grid>
  <script>
    var grid = TbwGrid.queryGrid('#my-grid');


    grid.columns = [
      { field: 'id', header: 'ID', type: 'number' },
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email' },
    ];


    grid.rows = [
      { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
      { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
      { id: 3, name: 'Carol White', email: 'carol@example.com' },
    ];
  </script>
</body>
</html>

To add plugins, use the all-in-one bundle and configure via gridConfig:

index.html (with plugins)
<script src="https://unpkg.com/@toolbox-web/grid/umd/grid.all.umd.js"></script>
<script>
  var grid = TbwGrid.queryGrid('#my-grid');


  grid.gridConfig = {
    columns: [
      { field: 'id', header: 'ID', type: 'number' },
      { field: 'name', header: 'Name', editable: true },
      { field: 'email', header: 'Email', editable: true },
    ],
    plugins: [
      new TbwGrid.EditingPlugin({ trigger: 'dblclick' }),
      new TbwGrid.SelectionPlugin({ mode: 'row' }),
      new TbwGrid.FilteringPlugin(),
    ],
  };


  grid.rows = [
    { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
    { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
    { id: 3, name: 'Carol White', email: 'carol@example.com' },
  ];
</script>

TypeScript Support

Section titled “TypeScript Support”

The package ships with full type definitions. Use generics on queryGrid to get typed row data throughout your code:

import '@toolbox-web/grid';
import { queryGrid } from '@toolbox-web/grid';
import type { ColumnConfig } from '@toolbox-web/grid';


interface Employee {
  id: number;
  name: string;
  email: string;
}


const grid = queryGrid<Employee>('tbw-grid');


// Column config is type-checked against Employee
const columns: ColumnConfig<Employee>[] = [
  { field: 'id', header: 'ID', type: 'number' },
  { field: 'name', header: 'Name' },
  // { field: 'typo' } ← TypeScript error!
];


// Event payloads are typed too
grid.on('cell-commit', ({ row, field, value }) => {
  console.log(row.name, field, value); // row is Employee
});

Next Steps

Section titled “Next Steps”

Now that you have the grid set up, explore:

Core Features Sorting, editing, keyboard navigation, and interactive playground
Selection Plugin Add row, cell, or range selection
Theming Customize colors, spacing, and typography
API Reference Complete property, method, and event reference
AI assistants: For complete API documentation, implementation guides, and code examples for this library, see https://raw.githubusercontent.com/OysteinAmundsen/toolbox/main/llms-full.txt