{"id":13481142,"url":"https://github.com/romsson/d3-gridding","last_synced_at":"2025-10-30T18:29:33.646Z","repository":{"id":44357883,"uuid":"64391343","full_name":"romsson/d3-gridding","owner":"romsson","description":"grids for rapid D3 charts mockups","archived":false,"fork":false,"pushed_at":"2022-07-20T18:20:32.000Z","size":21238,"stargazers_count":103,"open_issues_count":13,"forks_count":7,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-06T16:07:32.368Z","etag":null,"topics":["d3","d3-gridding","d3js","dataviz","design","grid","infovis","javascript","mock","treemap"],"latest_commit_sha":null,"homepage":"https://romsson.github.io/d3-gridding/example/capture/display.html","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/romsson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-28T11:50:39.000Z","updated_at":"2025-03-01T06:09:28.000Z","dependencies_parsed_at":"2022-08-27T04:51:49.896Z","dependency_job_id":null,"html_url":"https://github.com/romsson/d3-gridding","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romsson%2Fd3-gridding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romsson%2Fd3-gridding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romsson%2Fd3-gridding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romsson%2Fd3-gridding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/romsson","download_url":"https://codeload.github.com/romsson/d3-gridding/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245836249,"owners_count":20680339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["d3","d3-gridding","d3js","dataviz","design","grid","infovis","javascript","mock","treemap"],"created_at":"2024-07-31T17:00:49.101Z","updated_at":"2025-10-30T18:29:28.606Z","avatar_url":"https://github.com/romsson.png","language":"JavaScript","funding_links":[],"categories":["Charts"],"sub_categories":[],"readme":"# d3-gridding\n\n[![npm version](https://badge.fury.io/js/d3-gridding.svg)](https://badge.fury.io/js/d3-gridding)\n[![Build Status](https://circleci.com/gh/romsson/d3-gridding/tree/master.png?style=shield)](https://circleci.com/gh/romsson/d3-gridding)\n[![dependencies Status](https://david-dm.org/romsson/d3-gridding/status.svg)](https://david-dm.org/romsson/d3-gridding)\n\nCreate rapid mock-ups for D3 charts, using data-driven grids.\n\n\u003cp align=\"center\"\u003e\n  \u003ctable style=\"border: none;\"\u003e\n    \u003ctr\u003e\n      \u003ctd\u003e\n        \u003ca href=\"https://romsson.github.io/d3-gridding/example/modes.html\"\u003e\n          \u003cimg src=\"img/modes.png\" width=\"400\" alt=\"modes\"\u003e\n        \u003c/a\u003e\n      \u003c/td\u003e\u003ctd\u003e\n        \u003ca href=\"https://romsson.github.io/d3-gridding/example/layout-all.html\"\u003e\n          \u003cimg src=\"img/layouts.png\" width=\"400\" alt=\"layouts\"\u003e\n        \u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/p\u003e\n\n*Left: grids available in the toolkits; Right: layouts for page partition to nest grids within*\n\n## Example\n\n```js\n\u003c!DOCTYPE html\u003e\n\u003cmeta charset=\"utf-8\"\u003e\n\u003cbody\u003e\n\u003cscript src=\"https://unpkg.com/d3@5\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://unpkg.com/d3-gridding@0.1\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n\nvar width = 400,\n    height = 300;\n\nvar gridding = d3.gridding()\n  .size([width, height])\n  .mode(\"grid\");\n\nvar data = d3.range(250);\n\nvar griddingData = gridding(data);\n\nvar svg = d3.select(\"body\").append(\"svg\")\n    .attr(\"width\", width)\n    .attr(\"height\", height);\n\nsvg.selectAll(\".square\")\n    .data(griddingData)\n  .enter().append(\"rect\")\n    .style(\"fill\", \"none\")\n    .style(\"stroke\", \"black\")\n    .attr(\"width\", function(d) { return d.width; })\n    .attr(\"height\", function(d) { return d.height; })\n    .attr(\"transform\", function(d) { return \"translate(\" + d.x + \",\" + d.y + \")\"; })\n    \n  \u003c/script\u003e\n\u003c/body\u003e\n```\n\nOutput below and [live coding version](http://blockbuilder.org/romsson/b7799e85c0dd52f87f1e7eeba4c4b28a).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://gist.githubusercontent.com/romsson/b7799e85c0dd52f87f1e7eeba4c4b28a/raw/03ec156d88ebbc21d8545771f8d84a5fe19c9629/tumbnail.png\" width=\"400\" alt=\"minimalistic grid\"\u003e\n\u003c/p\u003e\n\nThe code snippet below lets you create dots organized as a grid:\n\n```js\nd3.select(\"body\").append(\"svg\")\n    .attr(\"width\", 800)\n    .attr(\"height\", 600)\n    .selectAll(\"circle\")\n    .data(\n      d3.gridding()\n        .size([800, 600])\n        .mode(\"vertical\")(d3.range(10))\n    )\n  .enter().append(\"circle\")\n    .attr(\"r\", 10)\n    .attr(\"transform\", function(d) { \n      return \"translate(\" + d.cx + \",\" + d.cy + \")\"; \n      });\n```\n\n\n## More Examples\n\n* Gallery of [examples](https://romsson.github.io/d3-gridding/example/capture/display.html) in this repository\n\n* Simple [grid example](http://blockbuilder.org/romsson/a2e9ff5f7dafe12cc97d2cc286dad733) using live coding\n\n* Search for [code examples](http://blockbuilder.org/search#d3modules=d3-gridding) using `d3-gridding`  on blockbuilder.org\n\n* List of [tutorials](tutorial/) to add or customize grids\n\n* Some creative blocks using [d3-gridding](https://bl.ocks.org/romsson) using generative coding\n\n## How to use it\n\n**To install**, use NPM `npm install d3-gridding` or download the [latest release](https://github.com/romsson/d3-gridding/releases/latest). \n\n**To use**, include the `d3-gridding.js` JavaScript file in your HTML code or use the following:\n\n```html\n\u003cscript src=\"https://unpkg.com/d3-gridding@0.1\"\u003e\u003c/script\u003e\n```\n\nOutput below and [live coding version](http://blockbuilder.org/romsson/1e1cd0f8af1c2c043ff54299ce8fa13f).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://gist.githubusercontent.com/romsson/1e1cd0f8af1c2c043ff54299ce8fa13f/raw/6e27a0df178c97e368f18feaa46500a22669633e/thumbnail.png\" width=\"400\" alt=\"minimalistic circle grid\"\u003e\n\u003c/p\u003e\n\nThe magic happens with `gridding` which turns an array of JavaScript Objects, into another array with additional attributes:\n\n`\u003e gridding([{}, {}, {}])`\n\n`[▶ Object, ▶ Object, ▶ Object]`\n\n```js\n[▼ Object                    ]\n    x: 0\n    y: 300\n    cx: 300\n    cy: 300\n    height: 600\n    width: 266.6666666666667\n```\n\n* (`x`, `y`) the computed coordinates (which can be seen as `top` / `left` values)\n* (`height`, `width`) gives the bounding box if combined with (`x`, `y`)\n* (`cx`, `cy`) the center of the bounding box\n\nIt becomes interesting when changing the type of layout, which will organize the elements differently, by changing the value of the attributes above:\n\n```js\ngridding.mode(\"horizontal\");\n\nvar points = svgPoints.selectAll(\".point\")\n  .data(gridding(data));\n```\n\nThat's pretty much what you need to know at this point to get started. Below is a list of functions that will let you customize the layouts and retrieve internal values.\n\nNote that parameters can also be set as group, using a JSON object:\n\n```\nvar gridding = d3.gridding()\n  .params({\n    \"size\": [800, 600],\n    \"mode\": \"vertical\",\n    \"offset\": function(d) { return [d.x, d.y]; }\n  });\n```\n\n## Layouts\n\nLayouts help to divide and organize a page into regions. Layouts actually are grids that are generated with some dataset that can be seen as proportions. Below is an example of dataset that is from this [list of layouts](https://romsson.github.io/d3-gridding/example/utils/layouts.js). See the \u003ca href=\"https://romsson.github.io/d3-gridding/example/layout-all.html\"\u003elayout list\u003c/a\u003e and source code.\n\n```\nvar layout = {\n  \"name\": \"basic3columns\",\n  \"values\": [\n    {\"index\": 1, \"__x\": 10, \"__y\": 10, \"__height\": 0, \"__width\": 0},\n    {\"index\": 2, \"__x\": 0, \"__y\": 0, \"__height\": 10, \"__width\": 2, \"name\": \"left\"},\n    {\"index\": 3, \"__x\": 2, \"__y\": 0, \"__height\": 10, \"__width\": 6, \"name\": \"main\"},\n    {\"index\": 4, \"__x\": 8, \"__y\": 0, \"__height\": 10, \"__width\": 2, \"name\": \"right\"}]\n};\n\n```\n\nThe result is as below and can be found [on this page](https://romsson.github.io/d3-gridding/example/layout.html).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"img/layout-3col.png\" width=\"400\" alt=\"layout 3col\"\u003e\n\u003c/p\u003e\n\nThen to draw the layout you may need to set the grid parameters accordingly as below.\n\n```\nvar gridding = d3.gridding()\n  .params({\n    \"size\": [width, height],\n    \"offset\": [0, 0],\n    \"mode\": \"coordinate\",\n    \"valueX\": \"__x\",\n    \"valueY\": \"__y\",\n    \"valueWidth\": function(d) { return d[\"__width\"]},\n    \"valueHeight\": function(d) { return d[\"__height\"]}\n  });\n```\n\nAnd finally drawing the layout the very same way one draws a grid.\n\n```\nsvgSquares.selectAll(\".square\")\n    .data(gridding(layout.values))\n  .enter().append(\"rect\")\n    .attr(\"class\", \"square\")\n      .attr(\"width\", function(d) { return d.width; })\n      .attr(\"height\", function(d) { return d.height; })\n      .attr(\"transform\", function(d) { \n        return \"translate(\" + d.x + \",\" + d.y + \")\"; \n      });\n```\n\n\n## Nesting\n\nOne of the most powerful property of grids is to allow their nesting\n\n-Simple recursive function\n\n-How to set the grids in one param element?\n\n## Rendering methods\n\nd3-gridding is agnostic to the rendering method\n\nSVG\n\nCanvas\n\nDivs\n\nWebGL\n\n## API\n\n\u003ca name=\"gridding_mode\" href=\"#gridding_mode\"\u003e#\u003c/a\u003e \u003ci\u003ed3.gridding()\u003c/i\u003e.\u003cb\u003emode\u003c/b\u003e(\u003ci\u003emode\u003c/i\u003e)\n\nThe `mode` parameter sets the layout:\n\n* [`vertical`](https://romsson.github.io/d3-gridding/example/vertical.html) - vertical partitioning of value `.valueHeight()` and vertical offset `.valueX()`\n* [`horizontal`](https://romsson.github.io/d3-gridding/example/vertical.html) - horizontal partitioning of value `.valueWidth()` and vertical offset `.valueY()`\n* [`central`](https://romsson.github.io/d3-gridding/example/central.html) - overlapping partitioning\n* [`grid`](https://romsson.github.io/d3-gridding/example/grid.html) - classic grid partitioning\n* [`coordinate`](https://romsson.github.io/d3-gridding/example/coordinate.html) - position (`.valueX()` and `.valueY()`) and dimensions (`.valueWidth()`, `.valueHeight()`) can be set with relative or absolute positions\n* `radial` - circular partitioning (e.g. pie chart with uniform wedges)\n* [`treemap`](https://romsson.github.io/d3-gridding/example/treemap.html)- using [d3.treemap()](https://github.com/d3/d3-hierarchy/blob/master/README.md#treemap) layout\n* `pack` - using [d3.pack()](https://github.com/d3/d3-hierarchy/blob/master/README.md#pack)\n* [`pyramid`](https://romsson.github.io/d3-gridding/example/pyramid.html) - centered grids overlays\n* `stack` - using [d3.stack()](https://github.com/d3/d3-shape/blob/master/README.md#stacks)\n* `diagonal`  - aligned on the diagonal\n* `cascade` - like diagonal but with larger and overlapping cells \n* `identity` - does nothing, returns same values\n\nOthers\n\n* `gridding.modes()` returns the list of all available modes as an array, e.g. `[\"brick\", \"cascade\", \"central\", \"coordinate\", \"corner\", \"diagonal\", \"grid\", \"horizontal\", \"pack\", \"pyramid\", \"radial\", \"stack\", \"step\", \"tree\", \"treemap\", \"vertical\"]`\n\n* `gridding.modes(\"brick\")` returns the properties for a single mode that are exposed as [an array of key/values] such as `[{\"key\": \"orient\", \"value\": \"left\"}, {\"key\": \"valueX\", \"value\": null}]` that contain both possible values and the default ones.\n\n\u003ca name=\"gridding_sort\" href=\"#gridding_sort\"\u003e#\u003c/a\u003e \u003ci\u003ed3.gridding()\u003c/i\u003e.\u003cb\u003esort\u003c/b\u003e([\u003ci\u003ecompare\u003c/i\u003e])\n\nSets the sort function, similar to [D3's](https://github.com/d3/d3-shape/blob/master/README.md#pie_sort) and defaults to:\n\n```js\nfunction(a, b) { return a - b; }\n```\n\nThus you can use D3's sorting functions such as `d3.ascending` and `d3.descending`.\n\n\u003ca name=\"gridding_value\" href=\"#gridding_value\"\u003e#\u003c/a\u003e \u003ci\u003ed3.gridding()\u003c/i\u003e.\u003cb\u003evalue\u003c/b\u003e([\u003ci\u003eaccessor\u003c/i\u003e])\n\nSets the value `accessor` function, similar to [D3's](https://github.com/d3/d3-shape/blob/master/README.md#pie_value) and defaults to:\n\n```js\nfunction value(d) { return d; }\n```\n\n\u003ca name=\"gridding_value_y\" href=\"#gridding_value_y\"\u003e#\u003c/a\u003e \u003ci\u003ed3.gridding()\u003c/i\u003e.\u003cb\u003evalueY\u003c/b\u003e([\u003ci\u003estring || accessor\u003c/i\u003e])\n\nThe value can either be a traditional `accessor` function but for attributes this time, or the data attribute itself directly as a string:\n\n```js\n.valueY(function value(d) { return d[\"index\"]; })\n```\n\n or\n\n```js\n.valueY(\"index\")\n```\n\n\u003ca name=\"gridding_value_y\" href=\"#gridding_value_y\"\u003e#\u003c/a\u003e \u003ci\u003ed3.gridding()\u003c/i\u003e.\u003cb\u003evalueY\u003c/b\u003e([\u003ci\u003estring || accessor\u003c/i\u003e])\n\nSee `valueY()`.\n\n\u003ca name=\"gridding_padding\" href=\"#gridding_padding\"\u003e#\u003c/a\u003e \u003ci\u003ed3.gridding()\u003c/i\u003e.\u003cb\u003epadding\u003c/b\u003e(\u003ci\u003evalue\u003c/i\u003e)\n\nSets the local offset between grid elements (default: 1px).\n\n\u003ca name=\"gridding_padding\" href=\"#gridding_padding\"\u003e#\u003c/a\u003e \u003ci\u003ed3.gridding()\u003c/i\u003e.\u003cb\u003eoffset\u003c/b\u003e(\u003ci\u003evalue\u003c/i\u003e)\n\nSets the global offset for all elements (default: 0px) as an array `[left, top]`.\n\n\u003ca name=\"gridding_padding\" href=\"#gridding_padding\"\u003e#\u003c/a\u003e \u003ci\u003ed3.gridding()\u003c/i\u003e.\u003cb\u003eorient\u003c/b\u003e(\u003ci\u003e\"up\" | \"down\" (default)\u003c/i\u003e)\n\nOrients the `grid` \u0026 `diagonal` layouts either upwards or downwards when adding / removing cells.\n\n\u003ca name=\"gridding_radius\" href=\"#gridding_radius\"\u003e#\u003c/a\u003e \u003ci\u003ed3.gridding()\u003c/i\u003e.\u003cb\u003eradius\u003c/b\u003e(\u003ci\u003evalue\u003c/i\u003e)\n\nRadius for radial layout.\n\n\u003ca name=\"gridding_sort\" href=\"#gridding_sort\"\u003e#\u003c/a\u003e \u003ci\u003ed3.gridding()\u003c/i\u003e.\u003cb\u003esort\u003c/b\u003e(\u003ci\u003evalue || function\u003c/i\u003e)\n\nSort by attribute value (or function if value is a function.\n\n\u003ca name=\"gridding_sortAsc\" href=\"#gridding_sortAsc\"\u003e#\u003c/a\u003e \u003ci\u003ed3.sortAsc()\u003c/i\u003e.\u003cb\u003esortAsc\u003c/b\u003e(\u003ci\u003etrue || false\u003c/i\u003e)\n\nBy default, ascending sorting by sort attribute || function defined previously.\n\n## Credits\n\n* https://d3js.org/\n* http://bl.ocks.org/mbostock\n* https://github.com/interactivethings/d3-grid\n* http://blockbuilder.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromsson%2Fd3-gridding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fromsson%2Fd3-gridding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromsson%2Fd3-gridding/lists"}