Skip to content

Add a complete example to README #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add a complete example to README #201

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 130 additions & 59 deletions packages/react-vega/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,83 +1,158 @@
# react-vega [![NPM version][npm-image]][npm-url]

> Use `vega` or `vega-lite` in `react` application smoothly!
> Easily add `vega` or `vega-lite` visualizations to your `react` application!

**DEMO**: http://vega.github.io/react-vega/

## Install

```bash
npm install react vega vega-lite react-vega --save
npm install vega vega-lite react-vega --save
```

## Versions

* `[email protected]` is rewritten in typescript with several API changes and now support both `vega` and `vega-lite`. If you are upgrading from `react-vega` or `react-vega-lite` version `6.x.x` to `7.x.x`, read this [migration guide](https://github.com/vega/react-vega/blob/master/CHANGELOG.md#-migration-guide).
* `[email protected]` is same with `5.x.x` but output are in different directories and exported as both `commonjs` and `es module`.
* `[email protected]` uses `vega` again.
* `[email protected]` has same interface with `3.x.x` except it uses the lightweight `vega-lib` instead of `vega`.
* `[email protected]` was update with breaking changes to support `[email protected]`.
* If you are looking to use `react` with `[email protected]`, please use `[email protected]`.
## Usage


## Example code

There are two approaches to use this library.

### Approach#1 Create class from spec, then get a React class to use

#### BarChart.js

See the rest of the spec in [spec1.js](https://github.com/vega/react-vega/blob/master/packages/react-vega-demo/stories/vega/spec1.js).
Let's say you have a [Vega specification](https://vega.github.io/vega/docs/specification/) for a bar chart that you want to display in your React application. Create a new file, `BarChart.js`, add your spec, and convert it into a React component with `createClassFromSpec`.

```js
import React, { PropTypes } from 'react';
import { createClassFromSpec } from 'react-vega';
// BarChart.js
import { createClassFromSpec } from "react-vega";

export default createClassFromSpec('BarChart', {
"width": 400,
"height": 200,
"data": [{ "name": "table" }],
"signals": [
const spec = {
width: 400,
height: 200,
data: [{ name: "table" }],
signals: [
{
"name": "tooltip",
"value": {},
"on": [
{"events": "rect:mouseover", "update": "datum"},
{"events": "rect:mouseout", "update": "{}"}
name: "tooltip",
value: {},
on: [
{ events: "rect:mouseover", update: "datum" },
{ events: "rect:mouseout", update: "{}" }
]
}
],
... // See the rest in packages/react-vega-demo/stories/vega/spec1.js
scales: [
{
name: "xscale",
type: "band",
domain: { data: "table", field: "category" },
range: "width"
},
{
name: "yscale",
domain: { data: "table", field: "amount" },
nice: true,
range: "height"
}
],
axes: [
{ orient: "bottom", scale: "xscale" },
{ orient: "left", scale: "yscale" }
],
marks: [
{
type: "rect",
from: { data: "table" },
encode: {
enter: {
x: { scale: "xscale", field: "category", offset: 1 },
width: { scale: "xscale", band: 1, offset: -1 },
y: { scale: "yscale", field: "amount" },
y2: { scale: "yscale", value: 0 }
},
update: {
fill: { value: "steelblue" }
},
hover: {
fill: { value: "red" }
}
}
},
{
type: "text",
encode: {
enter: {
align: { value: "center" },
baseline: { value: "bottom" },
fill: { value: "#333" }
},
update: {
x: { scale: "xscale", signal: "tooltip.category", band: 0.5 },
y: { scale: "yscale", signal: "tooltip.amount", offset: -2 },
text: { signal: "tooltip.amount" },
fillOpacity: [{ test: "datum === tooltip", value: 0 }, { value: 1 }]
}
}
}
]
};

const BarChart = createClassFromSpec({
spec
});

export default BarChart;
```

#### main.js
Now import and use `BarChart` like any other React component:

```js
import React from 'react';
import ReactDOM from 'react-dom';
import BarChart from './BarChart.js';
import React from "react";
import BarChart from "./BarChart.js";

const barData = {
table: [...]
table: [
{ category: "A", amount: 28 },
{ category: "B", amount: 55 },
{ category: "C", amount: 43 },
{ category: "D", amount: 91 },
{ category: "E", amount: 81 },
{ category: "F", amount: 53 },
{ category: "G", amount: 19 },
{ category: "H", amount: 89 }
]
};

function handleHover(...args){
console.log(args);
// Optional.
// signalListeners is only needed if you want to listen for chart interactions.
function handleHover(name, data) {
console.log({ name, data });
// {
// name: "tooltip",
// data: {
// amount: 28,
// category: "A",
// Symbol(vega_id): 810
// }
// }
}
const signalListeners = { tooltip: handleHover };

const signalListeners = { hover: handleHover };

ReactDOM.render(
<BarChart data={barData} signalListeners={signalListeners} />,
document.getElementById('bar-container')
);
export default function App() {
return <BarChart data={barData} signalListeners={signalListeners} />;
}
```

### Approach#2 Use `<Vega>` generic class and pass in `spec` for dynamic component.
Check out the result in this [CodeSandbox](https://codesandbox.io/s/react-vega-bar-chart-qecmh?file=/src/App.js)!

## Versions

* `[email protected]` is rewritten in typescript with several API changes and now support both `vega` and `vega-lite`. If you are upgrading from `react-vega` or `react-vega-lite` version `6.x.x` to `7.x.x`, read this [migration guide](https://github.com/vega/react-vega/blob/master/CHANGELOG.md#-migration-guide).
* `[email protected]` is same with `5.x.x` but output are in different directories and exported as both `commonjs` and `es module`.
* `[email protected]` uses `vega` again.
* `[email protected]` has same interface with `3.x.x` except it uses the lightweight `vega-lib` instead of `vega`.
* `[email protected]` was update with breaking changes to support `[email protected]`.
* If you are looking to use `react` with `[email protected]`, please use `[email protected]`.

Provides a bit more flexibility, but at the cost of extra checks for spec changes.

## Additional examples

The BarChart example took the approach of creating a React class from a spec, but there are two other options.

### `<Vega>`

One alternative is to use the generic `<Vega>` component; this provides a bit more flexibility, but at the cost of extra checks for spec changes.

#### main.js

Expand Down Expand Up @@ -107,23 +182,20 @@ const barData = {
table: [...]
};

function handleHover(...args){
console.log(args);
function handleHover(name, data){
console.log({name, data});
}

const signalListeners = { hover: handleHover };
const signalListeners = { tooltip: handleHover };

ReactDOM.render(
<Vega spec={spec} data={barData} signalListeners={signalListeners} />,
document.getElementById('bar-container')
);
```

### `<VegaLite>`


### Approach#3 Use `<VegaLite>` generic class and pass in `spec` for dynamic component.

Provides a bit more flexibility, but at the cost of extra checks for spec changes.
The last option is to use the generic `<VegaLite>` component and pass in a `spec`; this provides a bit more flexibility, but at the cost of extra checks for spec changes.

Also see packages/react-vega-demo/stories/ReactVegaLiteDemo.jsx for details

Expand Down Expand Up @@ -165,7 +237,6 @@ ReactDOM.render(
);
```


## API

### Props
Expand Down Expand Up @@ -208,11 +279,11 @@ In the example above, `vis.data('table')` will be passed as `dataset`.
- **signalListeners**:Object

All signals defined in the spec can be listened to via `signalListeners`.
For example, to listen to signal *hover*, attach a listener like this
For example, to listen to signal *tooltip*, attach a listener like this

```js
// better declare outside of render function
const signalListeners = { hover: handleHover };
const signalListeners = { tooltip: handleHover };

<Vega spec={spec} data={barData} signalListeners={signalListeners} />
```
Expand Down