Overview

Relevant source files

• README.md
• package.json
• packages/s2-core/CHANGELOG.md
• packages/s2-core/README.en-US.md
• packages/s2-core/README.md
• packages/s2-core/package.json
• packages/s2-react/CHANGELOG.md
• packages/s2-react/README.md
• packages/s2-react/package.json
• packages/s2-vue/CHANGELOG.md
• packages/s2-vue/README.md
• packages/s2-vue/package.json
• pnpm-lock.yaml
• s2-site/docs/manual/faq.zh.md
• s2-site/docs/manual/getting-started.zh.md
• s2-site/docs/manual/introduction.zh.md
• s2-site/package.json

What is S2?

S2 is a data-driven table visualization library for multi-dimensional cross-analysis. The name derives from "SpreadSheet".

The library provides:

• PivotSheet: Multi-dimensional cross-tabulation with hierarchical row/column headers
• TableSheet: Flat data tables with sorting, filtering, and freezing capabilities
• Framework adapters for React and Vue 3

Core package @antv/s2 is framework-agnostic. Wrapper packages @antv/s2-react and @antv/s2-vue provide component integration.

Sources: packages/s2-core/package.json5-6 packages/s2-core/src/sheet-type/pivot-sheet.ts1-50 packages/s2-core/src/sheet-type/table-sheet.ts1-50

Key Features

Multi-Dimensional Analysis

Configure hierarchical dimensions using S2DataConfig.fields:

High Performance

Performance optimizations include:

• Virtual scrolling: Only renders visible cells packages/s2-core/src/facet/utils.ts
• Cell reuse pool: Reduces object allocation packages/s2-core/src/facet/base-facet.ts
• RequestAnimationFrame batching for scroll events
• Achieves 50+ FPS with million-row datasets when scrolling (per changelog performance improvements)

Extensibility

Extension points via class inheritance and callbacks:

• Layout: Extend BaseFacet packages/s2-core/src/facet/base-facet.ts
• Cells: Extend BaseCell and derivatives packages/s2-core/src/cell/base-cell.ts
• Interactions: Extend BaseInteraction packages/s2-core/src/interaction/base-interaction.ts
• Data Processing: Extend BaseDataSet packages/s2-core/src/data-set/base-data-set.ts
• Callbacks: S2Options.dataCell, S2Options.layoutHierarchy, etc.

Rich Interactions

Built-in interaction classes packages/s2-core/src/interaction/:

• DataCellClick: Single/multi-selection with Ctrl/Cmd
• BrushSelection: Drag selection
• HoverEvent: Cell hover highlighting
• RowColumnResize: Resize row heights and column widths
• RangeSelection: Shift-click range selection

Framework Integration

• @antv/s2: Core SpreadSheet, PivotSheet, TableSheet classes
• @antv/s2-react: <SheetComponent> packages/s2-react/src/components/sheets/index.tsx
• @antv/s2-vue: <SheetComponent> packages/s2-vue/src/components/sheets/index.ts
• @antv/s2-react-components: <AdvancedSort>, <Export>, etc. packages/s2-react-components/src/

Sources: packages/s2-core/src/data-set/ packages/s2-core/src/facet/base-facet.ts packages/s2-core/src/interaction/ packages/s2-core/CHANGELOG.md50-142

Common Use Cases

S2 is used in scenarios requiring interactive tabular data analysis:

• Business intelligence dashboards: Multi-dimensional reports with subtotals and grand totals
• Data analysis tools: Spreadsheet interfaces with copy/paste, Excel export, conditional formatting
• Financial reporting: Hierarchical statements with frozen headers for large datasets
• E-commerce analytics: Sales analysis across region, category, and time dimensions
• Custom analytical scenarios: Trend analysis tables, strategy comparison sheets

The library handles data volumes ranging from hundreds to millions of rows through virtual scrolling and progressive rendering.

Sources: README.md53-56 s2-site/docs/manual/introduction.zh.md58-67

Package Structure

S2 is organized as a pnpm monorepo with four published NPM packages:

Published Packages

Package	Description	Main Exports
@antv/s2	Core rendering engine (framework-agnostic)	PivotSheet, TableSheet, SpreadSheet
@antv/s2-react	React components (React ≥16.9.0)	SheetComponent, useSpreadSheet
@antv/s2-vue	Vue 3 components (Vue ≥3.x)	SheetComponent (Composition API)
@antv/s2-react-components	Analysis components (antd ≥5.x)	AdvancedSort, Export, Switcher

Package Dependencies

Build Outputs

Each package provides three module formats:

Format	Entry	Target Use Case
ESM	esm/index.js	Modern bundlers with tree-shaking
CommonJS	lib/index.js	Node.js, legacy build tools
UMD	dist/*.min.js	Browser <script> tags, CDN (unpkg)

Example package.json entry points packages/s2-core/package.json29-42:

Sources: packages/s2-core/package.json29-52 packages/s2-react/package.json24-37 packages/s2-vue/package.json25-38 package.json1-25

Quick Start

Installation

Basic Usage - Vanilla JavaScript

React Component

Vue 3 Component

For detailed setup instructions, see Getting Started (page 1.1).

Sources: s2-site/docs/manual/getting-started.zh.md23-165 README.md88-112 packages/s2-core/README.md80-196

Core Architecture

S2 follows a pipeline architecture where configuration flows through data processing, layout calculation, and rendering.

Rendering Pipeline

Core Classes and Responsibilities

SpreadSheet packages/s2-core/src/sheet-type/spread-sheet.ts

• Abstract base class for table instances
• Manages initialization: initContainer(), initFacet(), initInteraction()
• Orchestrates render pipeline: render() method triggers layout and cell rendering
• Concrete implementations: PivotSheet, TableSheet

BaseDataSet packages/s2-core/src/data-set/base-data-set.ts

• Transforms S2DataConfig.data array into queryable structures
• Builds hierarchical Node trees for rows and columns
• Implementations: PivotDataSet (multi-level hierarchy), TableDataSet (flat columns)

BaseFacet packages/s2-core/src/facet/base-facet.ts

• Calculates cell positions via doLayout()
• Generates ViewMeta objects with coordinates and dimensions
• Manages viewport: calculateXYIndexes() determines visible cells
• Implementations: PivotFacet, TableFacet

BaseCell packages/s2-core/src/cell/base-cell.ts

• Renders individual cells to canvas via initCell()
• Draw methods: drawTextShape(), drawBackgroundShape(), drawBorderShape()
• Subclasses: DataCell, RowCell, ColCell, CornerCell, HeaderCell

RootInteraction packages/s2-core/src/interaction/root.ts

• Manages interaction state machine: InteractionStateInfo
• States: SELECTED, HOVER, BRUSH_SELECTED, etc.
• Coordinates with EventController packages/s2-core/src/interaction/event-controller.ts

Sources: packages/s2-core/src/sheet-type/spread-sheet.ts1-100 packages/s2-core/src/data-set/base-data-set.ts1-50 packages/s2-core/src/facet/base-facet.ts1-100 packages/s2-core/src/cell/base-cell.ts1-100 packages/s2-core/src/interaction/root.ts1-50

Configuration System

S2 uses three configuration objects passed to SpreadSheet constructor or update methods:

Configuration	TypeScript Interface	Purpose	Key Properties
Data	S2DataConfig	Data structure and content	fields, data, meta, sortParams
Options	S2Options	Display and behavior	width, height, style, interaction, frozen
Theme	ThemeCfg	Visual styling	palette, theme (object with cell styles)

Configuration Methods

Configuration Merging

Internally, configurations are merged using customMerge() utility:

Default configurations are defined in:

• packages/s2-core/src/common/constant/options.ts - DEFAULT_OPTIONS
• packages/s2-core/src/data-set/interface.ts - DEFAULT_DATA_CONFIG

Sources: packages/s2-core/src/sheet-type/spread-sheet.ts packages/s2-core/src/sheet-type/spread-sheet.ts packages/s2-core/src/common/constant/options.ts s2-site/docs/manual/faq.zh.md34-73

Interaction System

S2 provides built-in interactions through classes in packages/s2-core/src/interaction/

Built-in Interaction Classes

Class	File	Functionality
DataCellClick	data-cell-click.ts	Single/multi-cell selection (Ctrl/Cmd), cell activation
BrushSelection	brush-selection.ts	Drag to select multiple cells
RangeSelection	range-selection.ts	Shift-click range selection
HoverEvent	hover-event.ts	Cell hover highlighting and focus
RowColumnResize	row-column-resize.ts	Drag resize for row heights and column widths
SelectedCellMove	selected-cell-move.ts	Arrow key navigation between selected cells

Event Flow

Registering Custom Interactions

Extend BaseInteraction packages/s2-core/src/interaction/base-interaction.ts:

Sources: packages/s2-core/src/interaction/ packages/s2-core/src/interaction/base-interaction.ts1-50 packages/s2-core/src/interaction/event-controller.ts1-100 packages/s2-core/src/common/constant/events/

Extension Points

S2 supports customization through class inheritance and callback functions.

Extension by Class Inheritance

Extension by Callbacks

S2Options provides callback functions for customization without subclassing:

Callback	Interface	Purpose
dataCell	(viewMeta: ViewMeta) => DataCell	Custom data cell instances
rowCell	(node: Node) => RowCell	Custom row header cells
colCell	(node: Node) => ColCell	Custom column header cells
cornerCell	(node: Node) => CornerCell	Custom corner cells
layoutHierarchy	(facet, node) => void	Custom hierarchy layout
layoutArrange	(facet, nodes) => void	Custom node arrangement
layoutCoordinate	(facet, nodes) => void	Custom coordinate calculation

Example: Custom data cell via callback:

Custom Theme System

Themes are customized via ThemeCfg object packages/s2-core/src/common/interface/theme.ts:

Sources: packages/s2-core/src/cell/base-cell.ts packages/s2-core/src/facet/base-facet.ts packages/s2-core/src/data-set/base-data-set.ts packages/s2-core/src/interaction/base-interaction.ts packages/s2-core/src/common/interface/theme.ts

Technology Stack

Core Dependencies

S2 core package dependencies packages/s2-core/package.json75-85:

Dependency	Version	Purpose
@antv/g	^6.3.1	Canvas rendering engine
@antv/g-canvas	^2.2.0	Canvas renderer implementation
@antv/g-lite	^2.7.0	Lightweight renderer base
@antv/event-emitter	^0.1.3	Event system
lodash	^4.17.21	Utility functions
decimal.js	^10.5.0	Precise decimal arithmetic
flru	^1.0.2	LRU cache for cell reuse
tinycolor2	^1.6.0	Color manipulation

Optional Dependencies

Dependency	Requirement	Purpose
@antv/g2	>=5.1.21 (peerDependency)	Mini-chart rendering in cells

Framework Integration

@antv/s2-react packages/s2-react/package.json82-88:

• react >= 16.9.0 (peerDependency)
• react-dom >= 16.9.0 (peerDependency)
• ahooks ^3.8.0 (React hooks library)
• classnames ^2.5.1

@antv/s2-vue packages/s2-vue/package.json80-84:

• vue >= 3.x (peerDependency)
• @vueuse/core ^10.5.0 (Vue composition API utilities)
• @ant-design/icons-vue ^6.1.0

@antv/s2-react-components:

• antd >= 5.17.0 (peerDependency for UI components)

Sources: packages/s2-core/package.json75-99 packages/s2-react/package.json58-88 packages/s2-vue/package.json57-84

Browser Compatibility

S2 supports modern browsers with the following minimum versions:

Browser	Version
Edge	Latest 2 versions
Firefox	Latest 2 versions
Chrome	Latest 2 versions
Safari	Latest 2 versions

React and Vue wrappers follow their respective framework requirements. The core @antv/s2 package has no framework dependencies.

Sources: README.md126-132 s2-site/docs/manual/faq.zh.md12-14

Key Technologies

S2 is built on top of several core technologies:

Core Dependencies

• @antv/g: Canvas rendering engine (6.x)
• @antv/g-canvas: Canvas renderer implementation
• @antv/event-emitter: Event system
• lodash: Utility functions
• decimal.js: Precise decimal calculations
• tinycolor2: Color manipulation

Optional Dependencies

• @antv/g2: Chart library for mini-charts in cells (optional peer dependency)

Sources: packages/s2-core/package.json75-99

---

This overview provides the foundation for understanding S2's architecture and capabilities. For detailed information about specific systems, refer to the linked sections throughout this document.