npm package: @gramex/treemap
Description: Treemap Reusable component
Author: Ushasree Ginne
Latest version: 1.0.0

# gramex-treemap

A re-usable visual that renders treemaps from tabular data.

## Example

Given this [population dataset](/docs/population.json), you can render a treemap like this:

[![Population treemap](https://code.gramener.com/reuse/gramex-treemap/-/raw/main/docs/population.png)](docs/population.html ":include")

[Here is the source code for the map above](docs/population.html ":include :type=code")

## Installation

Install via `npm`:

```bash
npm install @gramex/treemap
```

Use locally as an ES module:

```html
<script type="module">
  import { treemap } from "./node_modules/@gramex/treemap/index.ts";
</script>
```

Use locally as a script:

```html
<script src="./node_modules/@gramex/treemap/treemap.min.js"></script>
<script>
  gramex.treemap(...)
</script>
```

Use via CDN as an ES Module:

```html
<script type="module">
  import { treemap } from "https://cdn.jsdelivr.net/npm/@gramex/treemap@5/treemap.js";
</script>
```

Use via CDN as a script:

```html
<script src="https://cdn.jsdelivr.net/npm/@gramex/treemap@5/treemap.min.js"></script>
<script>
  gramex.treemap(...)
</script>
```

## API

The `treemap()` function accepts the following parameters:

- `element`: the SVG element to render the treemap in. This may be an `<svg>` or a `<g>` element.
- `options`: an object with the following keys
  - `groups`: a list of 1 or more column names or functions to group the treemap by
  - `size`: a column name or function indicating the size of the treemap
  - `width`: optional width of the map. Defaults to the element's size (or the nearest SVG parent)
  - `height`: optional width of the map. Defaults to the element's size (or the nearest SVG parent)

`treemap()` returns an object with these keys:

- `layer(selector)` a function that lets you add new lements to each treemap node. Accepts a
  selector of the form `tag.className`, e.g. `rect.country`

## Draw rectangles

Use `layer('rect.country')` and style it to draw rectangles for each country.

[![Treemap with rectangles](https://code.gramener.com/reuse/gramex-treemap/-/raw/main/docs/rectangles.png)](docs/rectangles.html ":include")

[Source code](docs/rectangles.html ":include :type=code")

## Color the rectangles by Country

Use any d3 color scales available `scaleOrdinal(schemeTableau10)` and fill it for each group/country.

[![Treemap with rectangles](https://code.gramener.com/reuse/gramex-treemap/-/raw/main/docs/colorrectangles.png)](docs/colorrectangles.html ":include")

[Source code](docs/colorrectangles.html ":include :type=code")

## Color the rectangles by each Group

Use any d3 color scales available `scaleOrdinal(schemeTableau10)` and fill it for each group/country.

[![Treemap with rectangles](https://code.gramener.com/reuse/gramex-treemap/-/raw/main/docs/colorgroup.png)](docs/colorgroup.html ":include")

[Source code](docs/colorgroup.html ":include :type=code")

## Add labels

Use `layer('text')` and style it to draw labels for each country.

[![Treemap with labels](https://code.gramener.com/reuse/gramex-treemap/-/raw/main/docs/labels.png)](docs/labels.html ":include")

[Source code](docs/labels.html ":include :type=code")

## Truncate text

Use `layer('text')` and style it to draw labels for each country, and truncate text by passing your custom function in place of text.

[![Treemap with rectangles](https://code.gramener.com/reuse/gramex-treemap/-/raw/main/docs/truncate_text.png)](/docs/truncate_text.html ":include")

[Source code](docs/truncate_text.html ":include :type=code")

## Add multiple shapes

Use `layer('circle')` and style it to draw circle for each country.

Use `layer('div')` and style it to draw div for each country.

[![Treemap with rectangles](https://code.gramener.com/reuse/gramex-treemap/-/raw/main/docs/shapes.png)](docs/shapes.html ":include")

[Source code](docs/shapes.html ":include :type=code")

## Add tooltips

Use `layer('title')` and style it to draw circle for each rectangle.

Hover on rectangles in below Treemap to see tooltips.

[![Treemap with rectangles](https://code.gramener.com/reuse/gramex-treemap/-/raw/main/docs/tooltips.png)](docs/tooltip.html ":include")

[Source code](docs/tooltip.html ":include :type=code")

## Animate the shapes

Use .transition() on in update to animate the map

[![Treemap with rectangles](https://code.gramener.com/reuse/gramex-treemap/-/raw/main/docs/animate.png)](docs/animate.html ":include")

[Source code](docs/animate.html ":include :type=code")

## Documentation

- [**Home page**](https://gramener.com/gramex-treemap/)
- [**Source**](https://code.gramener.com/reusablecharts/gramex-treemap.git)

## Release Notes

- 1.0.0: 31 Oct 2023. Initial release of @gramex/treemap

## Authors

- Ullas Kakanadan <ullas.kakanadan@gramener.com>
- Charan Pendli <sricharan.pendli@gramener.com>
- Shahbaz Mohd <mohd.shahbaz@gramener.com>
- Ushasree Ginne <ushasree.ginne@gramener.com>
- S Anand <s.anand@gramener.com>

## License

[MIT](https://spdx.org/licenses/MIT.html)