6.0.16 • Published 1 year ago

@oglabs/grid v6.0.16

Weekly downloads
-
License
MIT
Repository
github
Last release
1 year ago

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

MIT license Build Status

Demo | Usage | Wiki

Screen capture

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.

NameRequiredTypeDescriptionDefault
widthtruenumberWidth of the grid container800
heighttruenumberHeight of the grid container800
columnCounttruenumberNo of columns in the grid200
rowCounttruenumberNo of rows in the grid200
rowHeighttruefunctionFunction that returns height of the row based on rowIndex(rowIndex) => 20
columnWidthtruefunctionFunction that returns width of the column based on columnIndex(columnIndex) => 100
itemRenderertrueFunctionReact component to render the cellnull
selectionRenderertrueFunctionReact component to render selected cellnull
scrollbarSizefalsenumberSize of the scrollbar17
showScrollbarfalsebooleanAlways show scrollbartrue
selectionBackgroundColorfalsestringBackground color of selected cellsrgba(66, 133, 244, 0.3)
selectionBorderColorfalsestringBorder color of bounding box of selected cellsrgba(66, 133, 244, 1)
selectionStrokeWidthfalsenumberBorder width of selection1
activeCellStrokeWidthfalsenumberBorder width of activeCell2
activeCellfalse{ rowIndex, columnIndex }Recently active cell that user has clickednull
selectionsfalseArrayArray of selected cell areas[]
mergedCellsfalseArrayArray of merged cell areas[]
cellAreasfalseArrayIncrease the range of certain cells[]
snapfalsebooleanSnaps to the next row or column as you scrollfalse
frozenRowsfalsenumberNo of frozen rows0
frozenColumnsfalsenumberNo of frozen columns0
showFrozenShadowfalsebooleanShow shadow in frozen columns/rowstrue
shadowSettingsfalseobjectCustomize shadow of frozen columns/rowstrue
onBeforeRenderRowfalseFunctionCalled right before a row is rendered, useful for react-tablenull
stagePropsfalseObjectKonva stage propsnull
childrenfalseFunctionInject React Konva shapes using childrennull
wrapperfalseFunctionInject custom context using a wrapper(children) => children
showFillHandlefalsebooleanShow fill handle at bottom right cornertrue
onFillHandleMouseDownfalseFunctionCallback fired user selects fill handlenull
fillSelectionfalseSelectionPropArea of selected fillnull
overscanCountfalsenumberNumber of items outside the visible viewport should be renderer at all times1

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