# bo-grid

> A fast, lightweight data grid for trading screens: realtime price boards, order books, ladders, grouping, pivot and tree data. Native to Svelte 5, with React and Vue components and a custom element for everything else. MIT.

Facts to get right before writing code against bo-grid:

- Package: `bo-grid` on npm. Svelte 5 is a peer dependency; React and Vue are optional peers.
- Svelte: `import { Grid, type ColumnDef, type GridRow } from 'bo-grid'`. Write Svelte 5 only: runes (`$state`, `$props`), snippets and callback props; never `export let`, `on:click` or `<slot>`.
- React: `import { BoGrid } from 'bo-grid/react'`, its `ref` is the grid API. Vue: `import { BoGrid } from 'bo-grid/vue'`, props as attributes, callbacks as events (`@cell-edit`). Anything else: `bo-grid/element` (`createBoGrid(config)`).
- Minimal usage: `<Grid {rows} {columns} height={400} />`. Every row needs a unique `id` (or set `getRowId`).
- A column's `type` picks how values show, sort and filter: `text`, `price`, `percent`, `volume`, `number`, `date`, `currency`, `heatmap`, `sparkline`, `progress`, `badge`, `tags` and more.
- Live data: keep rows as plain objects and write ticks with `api.patchRows(patches)`, fed by `createTickStream` from `bo-grid/realtime`. A column with `flash: 'auto'` flashes every change by itself.
- Separate entries, each paid for only when imported: `bo-grid/realtime`, `bo-grid/trading`, `bo-grid/ladder`, `bo-grid/react`, `bo-grid/vue`, `bo-grid/element`.
- Every prop, column option and API method, with types and defaults: https://bonguynvan.github.io/bo-grid/api.json
- The installed package carries these docs for its own version, one Markdown file per page: `node_modules/bo-grid/dist/docs/README.md`, with `api.json` beside it. In a project, `npx bo-grid init` writes a bo-grid section into AGENTS.md and installs the bo-grid skill, both pointing there.
- An error from bo-grid starts with a stable code (`BG2004: ...`), states the value it got and ends with `Fix:` and a link. Apply the fix as written; every code is listed at https://bonguynvan.github.io/bo-grid/docs/errors/

## Get started

- [Introduction](https://bonguynvan.github.io/bo-grid/docs.md): bo-grid is a fast, lightweight data grid for trading screens. It is native to Svelte 5, with components for React and Vue and a custom element for every other framework.
- [Quick start](https://bonguynvan.github.io/bo-grid/docs/getting-started.md): Install bo-grid and render a first grid in Svelte, React, Vue or plain JavaScript.
- [React, Vue & more](https://bonguynvan.github.io/bo-grid/docs/frameworks.md): The grid as a React or a Vue component, the <bo-grid> custom element for Angular and plain JavaScript, and server rendering in each.
- [SvelteKit & SSR](https://bonguynvan.github.io/bo-grid/docs/sveltekit.md): Use bo-grid in SvelteKit with no setup, render the grid on the server, load rows in a load function, and add a live feed in the browser.
- [AI coding agents](https://bonguynvan.github.io/bo-grid/docs/ai.md): Give a coding agent what it needs to write correct bo-grid code first time, with every page as Markdown, the docs inside the package, an index in llms.txt, an API manifest generated from the types, and rules for your AGENTS.md.

## Columns

- [Column definitions](https://bonguynvan.github.io/bo-grid/docs/columns.md): Describe each column once, with a key, a header and a type, and the grid handles display, sorting, filtering and export.
- [Column types](https://bonguynvan.github.io/bo-grid/docs/column-types.md): Pick a column type for each column, from prices and percentages to badges, ratings and progress bars, or register your own.
- [Custom cells](https://bonguynvan.github.io/bo-grid/docs/custom-cells.md): Draw any cell your own way with a Svelte snippet, a component or a plain render function, and add styled tooltips to cells and headers.
- [Conditional formatting](https://bonguynvan.github.io/bo-grid/docs/conditional-formatting.md): Paint data bars, icons and colour scales into numeric cells from the values themselves, with no custom cell code.
- [Computed columns](https://bonguynvan.github.io/bo-grid/docs/computed-columns.md): Derive a column's value from the whole row, such as a total, a ratio or a P&L, and sort, filter, total and export it like any other column.
- [Column sizing](https://bonguynvan.github.io/bo-grid/docs/column-sizing.md): Set fixed and flexible widths, let users resize columns, scale every column with the grid, and widen columns whose values outgrow them.
- [Moving & hiding](https://bonguynvan.github.io/bo-grid/docs/column-moving.md): Let users drag columns into a new order and hide or show them from a column menu or a Columns panel, or drive visibility from your own UI.
- [Pinned columns](https://bonguynvan.github.io/bo-grid/docs/pinned-columns.md): Keep key columns, such as a symbol or a total, in view on the left or right edge while the rest of the grid scrolls sideways.
- [Header groups](https://bonguynvan.github.io/bo-grid/docs/header-groups.md): Put a spanning parent header over related columns, such as Bid, Ask and Match on a price board.

## Rows

- [Row height & grid size](https://bonguynvan.github.io/bo-grid/docs/row-height.md): Set the row height for the density you want, give rows their own heights, and size the grid in pixels or to fill its container.
- [Row selection](https://bonguynvan.github.io/bo-grid/docs/row-selection.md): Add a checkbox column for selecting whole rows, keyed by row id so the selection survives sorting, filtering and live updates.
- [Row numbers](https://bonguynvan.github.io/bo-grid/docs/row-numbers.md): Add a spreadsheet-style row-number column that follows sorting and filtering and is announced by screen readers.
- [Row styles](https://bonguynvan.github.io/bo-grid/docs/row-styles.md): Style rows and cells from their data with classes, react to a row being opened, and give rows a right-click menu.
- [Row reordering](https://bonguynvan.github.io/bo-grid/docs/row-reordering.md): Let users drag rows into their own order with a handle, for task lists, watchlists and priorities.
- [Pinned rows](https://bonguynvan.github.io/bo-grid/docs/pinned-rows.md): Keep rows above the scroll, always in view, whether they are rows of your own or rows readers pin from the board.
- [Merged cells](https://bonguynvan.github.io/bo-grid/docs/merged-cells.md): Merge repeated values down a column, or let a cell span several columns, without changing the data underneath.
- [Master-detail](https://bonguynvan.github.io/bo-grid/docs/master-detail.md): Expand a row into a detail panel underneath it, drawn by a snippet with anything inside, including another grid.
- [Pagination](https://bonguynvan.github.io/bo-grid/docs/pagination.md): Show rows a page at a time with a pager and an optional rows-per-page choice, instead of one long scroll.

## Sorting & filtering

- [Sorting & filtering](https://bonguynvan.github.io/bo-grid/docs/sorting-filtering.md): Sort by one or more columns, search across every column, and filter each column with a menu matched to its type.
- [Custom filters](https://bonguynvan.github.io/bo-grid/docs/custom-filters.md): Register a filter kind of your own, with its own editor in the column's filter menu, when text, number, date and set filters do not fit.
- [Find in grid](https://bonguynvan.github.io/bo-grid/docs/find.md): A find bar on Ctrl/⌘+F that searches the cells' displayed text and steps through every match.

## Editing & selection

- [Inline editing](https://bonguynvan.github.io/bo-grid/docs/editing.md): Edit cells in place with an editor matched to the column type, validate the value, and write it back to your rows.
- [Custom editors](https://bonguynvan.github.io/bo-grid/docs/custom-editors.md): Replace a column's editor with your own component, parse typed or pasted text into values, and share settings across columns.
- [Cell selection & clipboard](https://bonguynvan.github.io/bo-grid/docs/selection.md): Select ranges of cells, copy and paste them as spreadsheet text, fill with a drag handle, and see live totals for a selection or the whole grid.
- [Keyboard & hotkeys](https://bonguynvan.github.io/bo-grid/docs/keyboard.md): The grid's full keyboard model, and hotkeys of your own that act on the focused row, such as B to buy and Delete to cancel.

## Grouping & pivot

- [Row grouping](https://bonguynvan.github.io/bo-grid/docs/grouping.md): Group rows by one or more columns into collapsible sections with live subtotals on each group header.
- [Server-side grouping](https://bonguynvan.github.io/bo-grid/docs/server-grouping.md): Show groups summarised on the server, and load each group's rows only when it is expanded.
- [Tree data](https://bonguynvan.github.io/bo-grid/docs/tree-data.md): Show hierarchical rows as an expandable tree, from children you already have or loaded from a server on expand.
- [Pivot tables](https://bonguynvan.github.io/bo-grid/docs/pivot.md): Turn flat rows into a pivot table, with row groups down the side, one column per value of a field, and an aggregate in each cell.

## Realtime

- [Live updates](https://bonguynvan.github.io/bo-grid/docs/realtime.md): Stream a market feed into the grid — plain rows patched in place, one batch a frame, with rows that keep their sort, go stale when a feed goes quiet and flash when they arrive.
- [Cell flashing](https://bonguynvan.github.io/bo-grid/docs/flashing.md): Flash a cell green or red when its value moves, show how far it moved, flash cells on demand, and keep a busy board's flashes cheap.
- [Tick streams](https://bonguynvan.github.io/bo-grid/docs/tick-stream.md): Coalesce a feed's messages per key and apply one bounded batch a frame with createTickStream, so a burst never costs more than the screen can show.
- [Worker feeds](https://bonguynvan.github.io/bo-grid/docs/worker-feed.md): Read a busy socket in a Web Worker with serveFeed, and take one coalesced batch a frame on the main thread with connectFeed.
- [Viewport streaming](https://bonguynvan.github.io/bo-grid/docs/viewport-streaming.md): Subscribe a feed to just the rows on screen with onViewportChange and createViewportSubscriptions, so a board of thousands of symbols streams only the few dozen in view.

## Trading

- [Market conventions](https://bonguynvan.github.io/bo-grid/docs/trading.md): Price-limit colours, tick sizes, session state, FX pips, crypto prices, basis points and 32nds — the market conventions of bo-grid/trading, as plain functions you wire into columns.
- [Order book](https://bonguynvan.github.io/bo-grid/docs/order-book.md): Keep an order book from a depth feed with createOrderBook — snapshot, incremental updates with sequence checks, grouping — and show it as stacked or side-by-side grid rows.
- [Depth ladder](https://bonguynvan.github.io/bo-grid/docs/depth-ladder.md): A price ladder with click-to-trade (DepthLadder), the windowing math for a ladder of your own, and a capped time and sales tape.
- [Orders & positions](https://bonguynvan.github.io/bo-grid/docs/orders-positions.md): An order blotter with status chips, new orders that flash, done orders that linger a moment (createLinger), and positions with realized and unrealized P&L from the fills (createPositions).
- [Alerts](https://bonguynvan.github.io/bo-grid/docs/alerts.md): Price alerts that fire once per crossing and stay lit until someone acknowledges them, with createAlerts from bo-grid/realtime.

## Large data

- [Server-side data](https://bonguynvan.github.io/bo-grid/docs/server-data.md): Back the grid with a row source that serves only the rows in view, so the dataset can be millions of rows on a server.
- [Wide grids](https://bonguynvan.github.io/bo-grid/docs/wide-grids.md): Render only the columns in view for grids with dozens or hundreds of columns, and highlight the column under the pointer.

## Styling

- [Theming](https://bonguynvan.github.io/bo-grid/docs/theming.md): Style the grid with a built-in preset, a token map of your own, or CSS variables, from colours to fonts, corner radius and density.
- [Localization](https://bonguynvan.github.io/bo-grid/docs/localization.md): Translate every string the grid shows and format numbers and dates for a locale, per grid.
- [Accessibility](https://bonguynvan.github.io/bo-grid/docs/accessibility.md): Grid and treegrid semantics with true row and column counts, a full keyboard model, visible focus and WCAG 2.1 AA contrast.

## Export & API

- [Export & import](https://bonguynvan.github.io/bo-grid/docs/export.md): Export rows to CSV or Excel, print every row, and turn CSV, TSV or JSON text back into rows.
- [Grid API](https://bonguynvan.github.io/bo-grid/docs/grid-api.md): The grid's handle for actions that are not state, such as scrolling to a row, focusing a cell, saving a layout or patching live rows.
- [Props reference](https://bonguynvan.github.io/bo-grid/docs/reference.md): Every Grid prop, column option and grid API method, generated from the TypeScript types.
- [Error codes](https://bonguynvan.github.io/bo-grid/docs/errors.md): Every error bo-grid throws has a stable code, says what went wrong with the value it got, gives the exact fix, and links here.

## Optional

- [API manifest](https://bonguynvan.github.io/bo-grid/api.json): props, column options and API methods as JSON, generated from the types.
- [Full reference in one file](https://bonguynvan.github.io/bo-grid/llms-full.txt)
- [Examples](https://bonguynvan.github.io/bo-grid/examples/): every example live, with its source.