{"id":16668179,"url":"https://github.com/danielberndt/grid-distribute","last_synced_at":"2025-10-29T13:02:56.867Z","repository":{"id":57254043,"uuid":"145739754","full_name":"danielberndt/grid-distribute","owner":"danielberndt","description":" Efficiently distribute elements on a grid according to their priority or score.","archived":false,"fork":false,"pushed_at":"2018-08-23T16:07:42.000Z","size":98,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-23T00:05:54.440Z","etag":null,"topics":["grid","layout-algorithm","masonry"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielberndt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-22T17:13:39.000Z","updated_at":"2023-04-26T02:03:35.000Z","dependencies_parsed_at":"2022-08-31T09:01:55.384Z","dependency_job_id":null,"html_url":"https://github.com/danielberndt/grid-distribute","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielberndt%2Fgrid-distribute","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielberndt%2Fgrid-distribute/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielberndt%2Fgrid-distribute/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielberndt%2Fgrid-distribute/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielberndt","download_url":"https://codeload.github.com/danielberndt/grid-distribute/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243313412,"owners_count":20271178,"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":["grid","layout-algorithm","masonry"],"created_at":"2024-10-12T11:16:30.027Z","updated_at":"2025-10-29T13:02:56.773Z","avatar_url":"https://github.com/danielberndt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# grid-distribute\n\nEfficiently distribute elements on a grid according to their priority or score.\n\nThis can be useful for placing components on a full-screen dashboard or images in a fixed-size gallery.\n\nIt's fully typed via typescript but can be used with plain javascript as well.\n\n## Setup\n\n```sh\nnpm install grid-distribute\n# or\nyarn add grid-distribute\n```\n\n## Usage:\n\n```js\nimport setupGrid from \"grid-distribute\";\n\nconst grid = setupGrid({width: 4, height: 3});\n\nconst elements = [{prio: 2}, {prio: 4}, {prio: 2}];\nconst result = grid.distribute({elements, getPriority: e =\u003e e.prio});\n```\n\nthe result will look like this:\n\n```js\n[\n  {\n    position: {top: 0, left: 0, width: 4, height: 2},\n    element: {prio: 4}\n  },\n  {\n    position: {top: 2, left: 0, width: 2, height: 2},\n    element: {prio: 2}\n  }\n  {\n    position: {top: 2, left: 2, width: 2, height: 2},\n    element: {prio: 2}\n  }\n]\n```\n\n## API\n\n### `setupGrid({width, height, maxRatio, minRatio}) =\u003e Grid`\n\nCalling `setupGrid` will find all valid tile sizes and returns a `Grid` object which you can use to distrbute your elements.\n\n#### `width`, `height` [required]\n\nAmount of rows and columns of your grid.\n\n#### `minRatio` default: `0.5`, `maxRatio` default: `2`\n\nWhen determining all valid tile sizes, you can use `minRatio` and `maxRatio` to prevent tiles with weird aspect ratios. A tile which is 3 columns wide and 2 rows high has a ratio of `3/2 -\u003e 1.5`\n\n### `Grid.distribute(options) =\u003e ElementWithPosition[]`\n\nThis function performs an [A*](https://en.wikipedia.org/wiki/A*_search_algorithm)-like search through the solution space and returns a solution in which elements are paired with positions.\n\nThe return value has the shape `[{element, position: {top, left, width, height}},...]`. `element` is the original element that you passed into the `elements` argument.\n\nThere is no guarantee that all elements will be placed onto the grid. Passing a high `skipMultiplier` to the options will favour solutions that fit as many elements as possible though.\n\n#### option: `elements: E[]` [required]\n\nPass a list of arbitrary objects that need to be put onto the grid.\n\n#### option: `getPriority: (element: E) =\u003e number` [required]\n\nPass a callback that extracts a priority value for an `element`. Priorities will be normalized by the algorithm, so it can be any number. Elements with higher priority will be assigned tiles with less costs. (i.e. typically a greater area).\n\n#### option: `costOfUnexplored: (element: E) =\u003e number` default: `() =\u003e 0.5`\n\nThis option deterimines the greediness of the algorithm by assigning an estimated cost to elements that haven't been placed yet.\n\nThe `cost` needs to be between `0` and `1`. Setting this value to `0` will perform an exhaustive search returning the optimal solution given the costs. This will result in thousands of iterations even for few elements placed on a grid. Setting this value to `1` will lead to very few iteration cycles leading to a sub-optimal solution since backtracking is deemed too expensive due to the high cost of unexplored solutions.\n\n#### option: `costOfEmptyCell: number` default: `0.75`\n\nThis option determines the cost of an empty cell in the final solution.\n\n#### option: `ratioDiffWeight: number` default: `0.1`\n\n`ratioDiff` refers to the relative size of the normalized element priority and the the ratio of the assigned tile area compared to the whole grid size.\n\nHere's an example: Let's assume there are two elements `e1` with a prio of `3` and `e2` with a prio of `1`. The normalized prios are `0.75` and `0.25` respectively.\n\nNow we try to determine the cost for assigning `e1` to a 3x2 tile on a 3x3 grid.\nThe tile takes up `6` of the `9` grid cells. So its ratio is about `0.66`. The ratio diff is determined by `1 - Math.min(tileRatio / elementRatio, elementRatio / tileRatio)`. So in our case it's `0.1111`. If the `elementRatio` would be half as big as the `tileRatio` or vice versa, the ratioDiff would be `0.5`\n\nThe `ratioDiffWeight` determines the weight of the `ratioDiff` when estimating the cost of placing this element. Setting it to `0` would mean that a ratio difference would not matter, and higher values would encourage solutions in which the `ratioDiff` is as small as possible at the expense of more iterations.\n\n#### option: `costsOfPlacement: ({element, position, grid, ratioDiffMultiplier}) =\u003e number[]` default: `defaultCostsOfPlacement`\n\nDetermine the cost multipliers when placing an element on a grid. The cost multipliers are an array of numbers in the range of `0` to `1`. These values get averraged. Higher values indicate a sub-optimal placement for the given element, whereas a cost of `0` would indicate a perfect placement.\n\nThe `defaultCostsOfPlacement` can be imported via `import {defaultCostsOfPlacement} from \"grid-distribute\"` and used as a basis for more specific cost calculations. It returns the weighted `ratioDiff` explained above, as well as costs for the horizontal and vertical distance from the center. This favours solutions in which higher prio elements will be closer to the center of the grid.\n\nHere's the description of the of the callback arguments:\n\n**`element: E`** the element that was just placed on the grid\n\n**`position: {left, top, height, width}`** the position of the element on the grid\n\n**`grid: {height, width}`** width and height of the grid\n\n**`ratioDiffMultiplier: number`** the cost as determined by the `ratioDiff` and the `ratioDiffWeight`\n\n#### option: `skipMultiplier: (element: E) =\u003e number` default: `1`\n\nThis option determines the cost of not placing the given element on the grid.\n\n### A note on costs:\n\nThe costs applied to an element are multiplied with the relative priority of that element. This means that higher-prio elements tend to be placed more favourably than lower-prio elements if you the same costs are applied to them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielberndt%2Fgrid-distribute","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielberndt%2Fgrid-distribute","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielberndt%2Fgrid-distribute/lists"}