Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/graphiquejs/graphique
An interactive visualization system for React based on the Grammar of Graphics
https://github.com/graphiquejs/graphique
charts d3 data-visualization grammar-of-graphics react
Last synced: 8 days ago
JSON representation
An interactive visualization system for React based on the Grammar of Graphics
- Host: GitHub
- URL: https://github.com/graphiquejs/graphique
- Owner: graphiquejs
- License: mit
- Created: 2020-07-12T04:05:42.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-12-11T22:28:39.000Z (16 days ago)
- Last Synced: 2024-12-14T14:04:05.366Z (13 days ago)
- Topics: charts, d3, data-visualization, grammar-of-graphics, react
- Language: TypeScript
- Homepage: https://graphique.dev
- Size: 7.29 MB
- Stars: 14
- Watchers: 3
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
An interactive visualization system for React based on the Grammar of Graphics
## Graphique
Graphique allows you to concisely create flexible and reusable interactive visualizations by:
- mapping variables in data to visual components or _aesthetics_ specified by [scales](#scales) (_how_ to draw)
- composing or layering relatively simple graphical objects or [geometries](#geoms) (_what_ to draw)
- using reasonable defaults that can be configured for flexibility
## Examples/Docs
Examples and docs: https://graphique.dev
## Usage
#### Creating a simple, interactive line chart
Install only the geometries you need.
```shell
npm install @graphique/graphique @graphique/geom-line @graphique/datasets
```
or
```shell
yarn add @graphique/graphique @graphique/geom-line @graphique/datasets
```
```jsx
import React from 'react'
import ReactDOM from 'react-dom'
import { GG } from '@graphique/graphique'
import { GeomLine } from '@graphique/geom-line'
import { stocks } from '@graphique/datasets'
// default basic line chart
const LineChart = () => {
return (
d.symbol === 'AAPL')}
aes={{
x: (d) => new Date(d.date),
y: (d) => d.marketCap,
}}
>
)
}
ReactDOM.render(, document.getElementById('root'))
```
## Responsive
To keep your Graphique visualization the width of its parent container, you only need to specify `isContainerWidth` and you'll get an appropriately-scaled and responsive version.
```jsx
d.symbol === 'AAPL')}
aes={{
x: (d) => new Date(d.date),
y: (d) => d.marketCap,
}}
isContainerWidth
>
```
## Design philosophy
Relative to existing data visualization tools and libraries for React applications, Graphique exists "above" low-level APIs and "below" high-level/out-of-the-box/"named chart" charting libraries.
As much as possible, the routine parts of visualizing data should be taken care of for you. This means (by default) you shouldn't need to manually create your own scales, axes, coordinate systems, tooltips, interactive legends, animated transitions, or responsive logic. But when it comes time, you can customize/override nearly everything to suit your specific needs.
With sensible defaults, Graphique aims to be just opinionated enough to make the process of creating highly customizable visualizations as streamlined as possible. Graphique is directly inspired by [ggplot2](https://ggplot2.tidyverse.org/), and under the hood it's built on [d3](https://d3js.org).
## A layered approach
```jsx
// empty / no geoms
// defaults provide:
// x/y scales, coordinate system,
// grid, axes, ticks, dimensions, theme
new Date(d.date),
y: (d) => d.marketCap,
}}
/>
```
Aesthetics/Scales
**_How to draw_**. The specifications for how data characteristics relate to visual characteristics (functional mappings/transformations applied to `data`).
| **Aesthetic** (**Scale**) | **Specifies** | **Notes** |
| ------------------------------------ | ------------------------------------------------------- | --------------------------------- |
| `x` (`ScaleX`) | x positions of geometry objects, axis creation |
| `y` (`ScaleY`) | y positions of geometry objects, axis creation |
| `fill` (`ScaleFill`) | fill color of geometry objects, groups if categorical |
| `stroke` (`ScaleStroke`) | stroke color of geometry objects, groups if categorical |
| `strokeDasharray` (`ScaleDashArray`) | dash pattern of geometry objects, groups | categorical only |
| `size` (`ScaleSize`) | size of geometry objects | continuous only, `GeomPoint` only |
| `group` (`n/a`) | explicit groups for geometry objects |
| `label` (`n/a`) | main label for geometry object tooltips |
| `key` (`n/a`) | uniqueness/identity of geometry objects |
You can add one or more `Scale`s directly to customize things like its type ([d3 scale](https://github.com/d3/d3-scale#api-reference)), domain, values, formatting, etc.
```jsx
// a log-transformed y scale with
// custom domain and formatted as USD
d.xVal,
y: (d) => d.yVal,
}}
>
`$${value.toLocaleString()}`}
/>
```
Geometries
**_What to draw_**. The shapes that give a visualization something to visualize.
- `GeomLine`: line charts and other kinds of lines
- `GeomPoint`: scatterplots, dotplots, and bubble charts
- `GeomTile`: rectangular charts like heatmaps
- `GeomBar`: bar charts (horizontal bars)
- `GeomCol`: column charts (vertical bars)
- `GeomHist`: histograms
- `GeomArea`: area + stacked area charts and ribbon-like things
- `GeomVLine`: vertical lines / markers
- `GeomHLine`: horizontal lines / markers
- TODO: `GeomLabel`, `GeomSmooth`, `GeomSegment`, `GeomDensity`, and more on the way!
Labels
Give the main parts flexible, human-readable labels.
- `header`
- `x`
- `y`
Legend
Each Geom includes a `` that can be added to your Graphique visualization. Continuous `aes`<->`data` return values get continuous legends. Categorical `aes`<->`data` return values get categorical legends.
Tooltip
Tooltips are provided for each Geom for free. They're configurable and you can roll your own based on the relevant contextual information (x value, y value, etc) with ``. If you'd prefer the Geom to not use a tooltip, you can turn it off by passing `showTooltip={false}` to the Geom.
Theme
Customize the look and feel of your Graphique visualizations.
```jsx
// a custom theme
```
## Roadmap
- more `Geom`s
- linked graphics inside ``
## Dev
### Testing
```sh
npm test
```
#### Run only some tests
For example, you can also choose to run only some tests with things like:
```sh
# run only GeomLine tests
npm test GeomLine
# run only Tooltip tests (multiple Geoms)
npm test Tooltip
```
### Demo local packages
For a development sandbox / place to try out new package changes locally, there's a Vite app in `./demo`.
You can start the demo app with:
```sh
npm run demo
```
### Publishing and releasing
Use `npm run release` to publish and release new version(s) of package(s).