roughViz.js

repository·master·Indexed 27 days ago

A JavaScript library for creating sketchy, hand-drawn styled charts in the browser using D3.js and rough.js. Version 2.0.5 supports various visualization types including Bar, BarH, Donut, Pie, Line, Scatter, StackedBar, Network, and Force charts. It allows data input via JavaScript objects or URLs to CSV, TSV, and JSON files, focusing on communication where intent and generality are more important than absolute precision.

Tokens: 3.7K
Snippets: 4
Records: 31
Agent score: 92%

What's inside rough-viz

Basic usage of roughViz.js

master

To use the library in an ESM environment, import roughViz. You must provide a container element (e.g., a div with a specific ID) for each chart you create. You can pass data as a JavaScript object or as a URL to a CSV/TSV file.

import roughViz from "rough-viz";

// 1. Create container elements in HTML
// <div id="viz0"></div>

// 2. Initialize a Bar chart from a CSV file
new roughViz.Bar({
    element: '#viz0',
    data: 'https://raw.githubusercontent.com/jwilber/random_data/master/flavors.csv',
    labels: 'flavor',
    values: 'price'
});

// 3. Initialize a Donut chart using an object
new roughViz.Donut({
    element: '#viz1',
    data: {
      labels: ['North', 'South', 'East', 'West'],
      values: [10, 5, 8, 3]
    },
    title: "Regions",
    roughness: 8,
    colors: ['red', 'orange', 'blue', 'skyblue'],
    stroke: 'black',
    strokeWidth: 3,
    fillStyle: 'cross-hatch',
    fillWeight: 3.5,
});

Install roughViz.js
master
You can install rough-viz via npm, or include it directly in your HTML using a CDN. There are also community wrappers available for React, Vue, and Python.
https://github.com/jwilber/roughviz/blob/master/README.md
Configure roughViz.Line
master
Create line charts. Unlike other charts, Line requires data to be provided via a URL to a csv or tsv file.
Required Parameters:
- element [string]: Id or class of container element.
- data: Path/URL to a csv or tsv.
- y1, y2, y3... [string]: Column names for each line. Each attribute prefaced with y will receive its own line.
Common Optional Parameters:
- circle [boolean]: Whether to add circles to data points (default: true).
- circleRadius [number]: Radius of circles (default: 10).
- colors [array|string]: Colors for the lines.
```
new roughViz.Line({
   element: '#viz0',
   data: 'https://raw.githubusercontent.com/jwilber/random_data/master/profits.csv',
   y1: 'revenue',
   y2: 'cost',
   y3: 'profit'
});
```
https://github.com/jwilber/roughviz/blob/master/README.md
Configure roughViz.Donut and roughViz.Pie
master
Create donut or pie charts.
Required Parameters:
- element [string]: Id or class of container element.
- data: Either an object {labels: [], values: []} or a string URL to a csv, json, or tsv file.
Common Optional Parameters:
- colors [array]: Array of colors for each segment.
- legend [boolean]: Whether to show a legend (default: true).
- legendPosition [string]: 'left' or 'right' (default: 'right').
- fillWeight [number]: Weight of inner paths (default: 0.85 for Donut, 0.5 for Pie).
```
new roughViz.Pie({
   element: '.viz',
   data: {labels: ['a', 'b'], values: [10, 20]}
});
```
https://github.com/jwilber/roughviz/blob/master/README.md
Configure roughViz.Bar and roughViz.BarH
master
Create vertical (Bar) or horizontal (BarH) bar charts.
Required Parameters:
- element [string]: Id or class of container element.
- data: Either an object {labels: [], values: []} or a string URL to a csv/tsv file (requires labels and values keys to specify column names).
Common Optional Parameters:
- roughness [number]: Roughness level (default: 1).
- color [string]: Color for each bar (default: 'skyblue').
- fillStyle [string]: Fill style (e.g., 'cross-hatch').
- font [string/number]: Font family. Use 0 for Gaegu or 1 for Indie Flower.
https://github.com/jwilber/roughviz/blob/master/README.md
Configure roughViz.Scatter
master
Create scatter plots.
Required Parameters:
- element [string]: Id or class of container element.
- data: Either an object {x: [], y: []} or a string URL to a csv/tsv file.
Common Optional Parameters:
- x, y [string]: If using a URL, specify the column names for x and y axes.
- radius [number]: Circle radius (default: 8).
- colorVar [string]: If using a URL, specify an ordinal column to color points by.
- highlightLabel [string]: If using a URL, specify a column to display on hover instead of (x, y) values.
https://github.com/jwilber/roughviz/blob/master/README.md
Configure roughViz.StackedBar
master
Create stacked bar charts.
Required Parameters:
- element [string]: Id or class of container element.
- data: An array of objects.
- labels [string]: The key in the data objects used for the labels.
Example Data Structure: [{month: 'Jan', A: 20, B: 5}, {month: 'Feb', A: 25, B: 10}]
```
new roughViz.StackedBar({
   element: '#vis0',
   data: [
       {month:'Jan', A:20, B: 5},
       {month:'Feb', A:25, B: 10},
   ],
   labels: 'month',
});
```
https://github.com/jwilber/roughviz/blob/master/README.md
Configure roughViz.Pie options
master
When instantiating a Pie chart, you can provide the following configuration options in the opts object:
- data: An array of objects OR a string path to a .csv, .tsv, or .json file.
- labels: The key in your data object representing the labels (required if data is an object).
- values: The key in your data object representing the numerical values (required if data is an object).
- margin: An object { top, right, bottom, left } (defaults to { top: 50, right: 20, bottom: 10, left: 20 }).
- colors: An array of color strings.
- roughness: A number controlling the sketchiness (capped at 30).
- strokeWidth: The width of the chart strokes (defaults to 0.75).
- innerStrokeWidth: The width of the inner strokes (defaults to 0.75).
- fillWeight: The weight of the fill (defaults to 0.85).
- highlight: A color string used to highlight slices on mouseover.
- legend: Boolean indicating whether to show the legend (defaults to true).
- legendPosition: Position for the legend (e.g., 'right').
- title: A string for the chart title.
- interactive: Boolean to enable tooltips and hover effects (if supported by the base class).
https://github.com/jwilber/roughviz/blob/master/src/Pie.js

Configure Bar chart options

master

When instantiating a Bar chart, you can provide the following configuration options in the opts object:

Option	Type	Default	Description
`data`	`Object` or `string`	Required	Data object or path to a `.csv`/`.tsv` file
`container`	`HTMLElement`	Required	The DOM element where the chart will be rendered
`margin`	`Object`	`{ top: 20, right: 10, bottom: 20, left: 20 }`	Chart margins
`color`	`string`	`'red'`	Fill color of the bars
`highlight`	`string`	`'coral'`	Color of the bar on hover
`roughness`	`number`	Calculated	The roughness of the sketchy lines
`stroke`	`string`	`'black'`	Color of the bar outlines
`strokeWidth`	`number`	`1`	Width of the bar outlines
`axisStrokeWidth`	`number`	`0.5`	Width of the axis lines
`axisRoughness`	`number`	`0.5`	Roughness of the axis lines
`innerStrokeWidth`	`number`	`1`	Width of the inner stroke
`fillWeight`	`number`	`0.5`	Weight of the fill
`axisFontSize`	`string`	Auto-calculated	Font size for axis labels
`labels`	`string`	Auto-detected	Key for labels if using object data
`values`	`string`	Auto-detected	Key for values if using object data
`xValueFormat`	`string`	`undefined`	D3 format string for x-axis values
`yValueFormat`	`string`	`undefined`	D3 format string for y-axis values
`padding`	`number`	`0.1`	Padding between bars
`xLabel`	`string`	`''`	Text for the x-axis label
`yLabel`	`string`	`''`	Text for the y-axis label
`labelFontSize`	`string`	`'1rem'`	Font size for axis labels
`title`	`string`	`undefined`	Chart title
`titleFontSize`	`string`	Auto-calculated	Font size for the chart title
`interactive`	`boolean`	`false`	Enables tooltips and hover effects
`responsive`	`boolean`	`true`	Automatically redraws on window resize

Configure BarH options

master

When instantiating BarH, you can pass a configuration object with the following properties:

Option	Default	Description
`el`	Required	The DOM element or selector where the chart will be rendered.
`data`	Required	An object `{ labels: [], values: [] }` or a string URL to a `.csv`/`.tsv` file.
`margin`	`{ top: 50, right: 20, bottom: 50, left: 100 }`	Object defining chart margins.
`color`	`'red'`	The primary fill color of the bars.
`highlight`	`'coral'`	The color used when hovering over a bar.
`roughness`	Calculated	Controls the 'sketchy' look of the bars.
`stroke`	`'black'`	The color of the bar outlines.
`strokeWidth`	`1`	The width of the bar outlines.
`axisStrokeWidth`	`0.5`	The width of the axis lines.
`axisRoughness`	`0.5`	The roughness of the axis lines.
`innerStrokeWidth`	`1`	The width of the inner stroke of the bars.
`fillWeight`	`0.5`	The density of the hachure fill.
`axisFontSize`	`undefined`	Font size for axis labels. If undefined, it scales automatically.
`labels`	Inferred	The key in the data object representing labels (if data is an object).
`values`	Inferred	The key in the data object representing values (if data is an object).
`xValueFormat`	`undefined`	D3 format string for X-axis values.
`yValueFormat`	`undefined`	D3 format string for Y-axis values.
`padding`	`0.1`	Band scale padding for the Y-axis.
`xLabel`	`''`	Text for the X-axis label.
`yLabel`	`''`	Text for the Y-axis label.
`labelFontSize`	`'1rem'`	Font size for axis and bar labels.
`title`	`undefined`	The title text for the chart.
`titleFontSize`	`undefined`	Font size for the chart title.
`interactive`	`true`	Whether to enable mouseover tooltips and highlighting.

Load data from files in roughViz.Pie
master
The Pie chart can automatically fetch and parse data if the data option is a string ending in .csv, .tsv, or .json.
```
const opts = {
  data: 'path/to/data.csv',
  labels: 'category',
  values: 'amount',
  title: 'Data from CSV'
};

new Pie(opts);
```
https://github.com/jwilber/roughviz/blob/master/src/Pie.js
Redraw or remove a Pie chart
master
To update an existing chart instance with new data or options, use the .redraw(opts) method. To completely remove the chart and its SVG elements from the DOM, use the .remove() method.
https://github.com/jwilber/roughviz/blob/master/src/Pie.js