@oglabs/grid v6.0.16
Declarative Canvas Grid
Canvas table grid to render large set of tabular data. Uses virtualization similar to react-window
and React-Konva for primitives such as Rect, Text, Shape etc
Features
- :electron: React powered declarative library
- :100: Virtualized: Only visible cells are rendered
- :bulb: Performant: Canvas implementation - 55-60fps (re-render) and 40-60fps (scroll)
- :scroll: Supports scrolling using native scrollbars
- :computer: Supports both Fixed and Variable sized grids
- :fire: Freeze rows and columns
- :white_square_button: Merge rows and columns
- :hand: Resizable headers
- :deciduous_tree: Create Tree tables
- :musical_keyboard: Keyboard accessible
- :page_with_curl: Pagination sync/async
- :hammer_and_wrench: Fully typed API written in TypeScript
- :rainbow: Full Theming and Context Support
- :anchor: Fill handle support
- :feet: Customizable undo/redo support
- :iphone: Mobile/Touch device support
- :muscle: Highly customizable using react-konva
Why another canvas grid library
Born out of frustration, having to deal with complicated imperative canvas libraries, I wanted to create something easy to understand and declarative in nature. This Grid primitive is built on top of React Konva making it easy to customize and extend. Take a look at the storybook to learn more.
Installation
npm
npm install @oglabs/grid --save
yarn
yarn add @oglabs/grid
Compatiblity
Konva grid will work in any browser that supports react, konva and canvas element.
Integrations/Examples
Konva Grid is a pure renderer, that will work with many third-party table plugins
1. React-table
https://github.com/kmhari/og/tree/master/examples/react-table
Uses react-table to create grouped headings and rows, and display on Konva Grid
2. Excel worksheet
https://github.com/kmhari/og/tree/master/examples/excel-worksheet
3. Zustand - More control over cell level re-rendering
https://github.com/kmhari/og/tree/master/examples/zustand
More examples coming soon.
Usage
import { Grid, Cell } from "@oglabs/grid";
import { Group, Text, Rect } from "react-konva";
const App = () => {
const data = {
[[1, 2]]: "Hello world",
};
return (
<Grid
rowCount={100}
columnCount={100}
width={800}
height={800}
rowHeight={(rowIndex) => 20}
columnWidth={(columnIndex) => 100}
itemRenderer={(props) => (
<Cell {...props} value={data[[props.rowIndex, props.columnIndex]]} />
)}
/>
);
};
Props
This is the list of props that are meant to be used to customise the konva-grid
behavior.
Name | Required | Type | Description | Default |
---|---|---|---|---|
width | true | number | Width of the grid container | 800 |
height | true | number | Height of the grid container | 800 |
columnCount | true | number | No of columns in the grid | 200 |
rowCount | true | number | No of rows in the grid | 200 |
rowHeight | true | function | Function that returns height of the row based on rowIndex | (rowIndex) => 20 |
columnWidth | true | function | Function that returns width of the column based on columnIndex | (columnIndex) => 100 |
itemRenderer | true | Function | React component to render the cell | null |
selectionRenderer | true | Function | React component to render selected cell | null |
scrollbarSize | false | number | Size of the scrollbar | 17 |
showScrollbar | false | boolean | Always show scrollbar | true |
selectionBackgroundColor | false | string | Background color of selected cells | rgba(66, 133, 244, 0.3) |
selectionBorderColor | false | string | Border color of bounding box of selected cells | rgba(66, 133, 244, 1) |
selectionStrokeWidth | false | number | Border width of selection | 1 |
activeCellStrokeWidth | false | number | Border width of activeCell | 2 |
activeCell | false | { rowIndex, columnIndex } | Recently active cell that user has clicked | null |
selections | false | Array | Array of selected cell areas | [] |
mergedCells | false | Array | Array of merged cell areas | [] |
cellAreas | false | Array | Increase the range of certain cells | [] |
snap | false | boolean | Snaps to the next row or column as you scroll | false |
frozenRows | false | number | No of frozen rows | 0 |
frozenColumns | false | number | No of frozen columns | 0 |
showFrozenShadow | false | boolean | Show shadow in frozen columns/rows | true |
shadowSettings | false | object | Customize shadow of frozen columns/rows | true |
onBeforeRenderRow | false | Function | Called right before a row is rendered, useful for react-table | null |
stageProps | false | Object | Konva stage props | null |
children | false | Function | Inject React Konva shapes using children | null |
wrapper | false | Function | Inject custom context using a wrapper | (children) => children |
showFillHandle | false | boolean | Show fill handle at bottom right corner | true |
onFillHandleMouseDown | false | Function | Callback fired user selects fill handle | null |
fillSelection | false | SelectionProp | Area of selected fill | null |
overscanCount | false | number | Number of items outside the visible viewport should be renderer at all times | 1 |
Methods
scrollTo({ scrollLeft, scrollTop }
Scrolls the grid to a specified x,y
position relative to the container
resetAfterIndices({ rowIndex, columnIndex })
Imperatively trigger re-render of the grid after specified rowIndex
or columnIndex
getScrollPosition()
Get the current scroll position of the grid.
const gridRef = useRef()
const { scrollLeft, scrollTop } = gridRef.current.getScrollPosition()
isMergedCell({ rowIndex, columnIndex })
Check if a cell at a coordinate is a merged cell
getCellBounds({ rowIndex, columnIndex })
Returns a selection IArea
for a particular cell. Useful to get selection area of a merged cell
getCellCoordsFromOffsets(x , y)
Returns exact rowIndex
and columnIndex
from a x
and y
cordinate. Useful if you want to get cell coords based on mouse position
getCellOffsetFromCoords({ rowIndex, columnIndex })
Returns offset position { x, y, width, height }
of a cell
stage
Access Konva stage
instance
const gridRef = useRef()
<Grid
ref={gridRef}
>
const stage = gridRef.current.stage
Passing Contexts
React Konva uses react-reconciler
to create a custom React renderer. Which means Top Level Context is not available inside the canvas. We provide a simple wrapper
prop to pass Context to the Grid
const ThemeContext = React.createContext({})
const theme = { color: 'yellow' }
<Grid
wrapper={(children) => {
return (
<ThemeContext.Provider value={theme}>
{children}
</ThemContext.Provider>
)
}}
/>
This will let you use ThemeContext in any of the React Konva components. To access theme inside Cell
, you could do
const Cell = ({ x, y, width, height }) => {
const theme = useContext(ThemeContext)
return (
<Rect
fill={theme.color}
x={x}
y={y}
width={width}
height={height}
>
)
}
Storybook
Examples can be found in stories
directory. To run storybook, enter the following commands
yarn
yarn run storybook
Contribution
Feel free to fork and submit pull requests
git clone https://github.com/kmhari/og.git
cd grid
yarn
// Run storybook
yarn storybook
1 year ago