DOCSEARCHbyAlgolia
Submit Docs

ReactGrid Documentation

repository·develop·Indexed 23 days ago

https://github.com/silevis/reactgrid

An open-source React component for building spreadsheet-like interfaces. ReactGrid supports data editing, cell spanning, sticky rows and columns, column resizing, and range selection. It provides a flexible API via the PublicModel for state management and allows for custom cell rendering through the CellTemplate interface. Key features include built-in cell templates (Date, Number, Text, Checkbox, Dropdown), keyboard shortcuts, and a configurable context menu.

Tokens
2.3K
Snippets
1
Records
21
Agent score
82%

What's inside ReactGrid

  1. Overview of ReactGrid features

    develop

    ReactGrid is an open-source React component designed for displaying and editing data in a spreadsheet-like interface. It provides advanced spreadsheet capabilities including:

    • Data Management: Handling data changes and custom cell types.
    • Layout & Navigation: Column resizing, column/row reordering, sticky rows/columns, and range selection.
    • Editing & Interaction: Keyboard shortcuts, spanned cells, fill handle, and styled ranges.
    • Customization: Custom styling, customizable behaviors, and an API hook for programmatic interaction with the grid.

  2. Get started with ReactGrid v5-alpha

    develop

    The latest version (v5-alpha) is available. To get started quickly, you can visit the official documentation site for detailed guides and setup instructions.

    https://silevis.github.io/reactgrid/docs/5.0/1-getting-started

  3. Configure environment for ReactGrid Cypress tests

    develop

    When running Cypress tests for ReactGrid on Windows, test results may be affected by screen resolution and scaling. To ensure consistent results and avoid false failures, configure your environment as follows:

    • Screen Resolution: 1980 x 1020
    • Scaling: 100%

    Note: These constraints are not required for MacOS, as no resolution-based differences have been observed there.

  4. Core components of ReactGrid

    develop

    ReactGrid provides a suite of components for rendering complex grids. The primary entry point for users is likely the ReactGrid component, which orchestrates the grid rendering, cell editing, and pane management. Other key components include:

    • ReactGrid: The main grid component.
    • GridRenderer: Responsible for rendering the grid structure.
    • CellRenderer: Handles the rendering of individual cells.
    • CellEditor: Provides the interface for editing cell content.
    • Pane and PanesRenderer: Manage the viewable areas (panes) of the grid.
    • LegacyBrowserGridRenderer: A specialized renderer for older browser compatibility.

  5. Core models and state management in ReactGrid

    develop

    ReactGrid uses a structured model system to manage grid data, selection, and behavior. Key models include:

    • InternalModel: The underlying data model for the grid.
    • CellMatrix: Represents the grid's data structure.
    • CellMatrixBuilder: A utility for constructing CellMatrix instances.
    • Range: Defines a selection or a specific area within the grid.
    • State: Manages the internal state of the grid.
    • Behavior: Defines how the grid responds to user interactions.
    • AbstractPointerEventsController: An abstraction for handling pointer-based events.

  6. Understand Cell types: Uncertain vs Compatible

    develop

    ReactGrid uses different cell type wrappers to manage data flow and validation:

    1. Uncertain<TCell>: A partial version of your cell type where all fields are optional. This is typically used when receiving raw data or during the initial stages of cell creation.
    2. Compatible<TCell>: An extended version of your cell type that guarantees the presence of text (string) and value (number) properties. This is the standard format used by the grid for rendering and internal logic.

    When creating a CellTemplate, you must implement getCompatibleCell to transform an Uncertain cell into a Compatible one.

  8. Understand ReactGrid Cypress test status legend

    develop

    The Cypress test suite uses specific markers and patterns to indicate the health and reliability of tests:

    • ✅ (Written correctly): Standard passing tests.
    • 🔴 (Should be skipped): Tests that are not working correctly or can produce incorrect outcomes. These are marked using it.skip().
    • 🟠 (Orange dot): Tests that are currently being skipped because they expose an existing bug (often marked with a // 🟠 TODO comment).

  9. Use the ReactGrid component

    develop
    The primary entry point for the library is the ReactGrid component. It is designed to be used within a React application to render a high-performance grid. Based on the project's test entrypoint, it accepts a config object to define its behavior and features.

  10. Customize the context menu with onContextMenu

    develop

    You can compose your own context menu by providing an onContextMenu handler in ReactGridProps. This handler is called when a user opens the context menu inside the grid.

    It receives:

    • selectedRowIds: Array of selected row IDs.
    • selectedColIds: Array of selected column IDs.
    • selectionMode: The current SelectionMode ('row', 'column', or 'range').
    • menuOptions: The default built-in menu options (e.g., copy, cut, paste).
    • selectedRanges: An array of CellLocation[] representing the selected areas.

    Return an array of MenuOption objects to display in the menu.

  11. Create custom cell templates with CellTemplate

    develop

    To implement custom cell rendering and behavior, implement the CellTemplate<TCell> interface. This interface allows you to control how a cell is validated, focused, updated, styled, and rendered.

    Required and optional methods:

    • getCompatibleCell(uncertainCell): Required. Validates and converts an Uncertain<TCell> (a cell with optional fields) into a Compatible<TCell> (a cell with guaranteed text and value fields).
    • render(cell, isInEditMode, onCellChanged): Required. Returns the React node to display. Use onCellChanged to commit updates.
    • isFocusable?(cell): Returns whether the cell can receive focus.
    • update?(cell, cellToMerge): Merges new data into the existing cell.
    • handleKeyDown?(...): Handles keyboard events and can trigger edit mode.
    • getStyle?(cell, isInEditMode): Returns custom CellStyle properties.
    • getClassName?(cell, isInEditMode): Returns CSS class names for the cell.

  12. Use the ReactGrid library entrypoint

    develop
    The @silevis/reactgrid library provides a complete set of tools for building interactive grids. The main entrypoint exports the core ReactGrid component, the PublicModel for state management, cell templates, and utility functions for handling key codes and cell properties.