{"id":13394101,"url":"https://github.com/e-oj/Magic-Grid","last_synced_at":"2025-03-13T19:31:57.441Z","repository":{"id":42479976,"uuid":"157127995","full_name":"e-oj/Magic-Grid","owner":"e-oj","description":"A simple, lightweight Javascript library for dynamic grid layouts.","archived":false,"fork":false,"pushed_at":"2024-09-04T15:48:54.000Z","size":9895,"stargazers_count":3152,"open_issues_count":22,"forks_count":141,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-03-11T18:35:33.837Z","etag":null,"topics":["grid","grid-layout","layout"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/magic-grid","language":"JavaScript","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/e-oj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-11T22:35:29.000Z","updated_at":"2025-03-04T10:28:46.000Z","dependencies_parsed_at":"2024-01-06T01:55:17.217Z","dependency_job_id":"09aed422-2f43-4c77-b2d4-625e40d2013c","html_url":"https://github.com/e-oj/Magic-Grid","commit_stats":{"total_commits":165,"total_committers":11,"mean_commits":15.0,"dds":"0.47878787878787876","last_synced_commit":"3f45a02100c667b5050525933ebe779f5c7979bc"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-oj%2FMagic-Grid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-oj%2FMagic-Grid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-oj%2FMagic-Grid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-oj%2FMagic-Grid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/e-oj","download_url":"https://codeload.github.com/e-oj/Magic-Grid/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243469239,"owners_count":20295715,"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","grid-layout","layout"],"created_at":"2024-07-30T17:01:08.968Z","updated_at":"2025-03-13T19:31:56.792Z","avatar_url":"https://github.com/e-oj.png","language":"JavaScript","readme":"[![MIT License](https://img.shields.io/npm/l/magic-grid.svg?style=for-the-badge)](https://www.npmjs.com/package/magic-grid)\n[![Downloads](https://img.shields.io/npm/dt/magic-grid.svg?style=for-the-badge)](https://www.npmjs.com/package/magic-grid)\n\u003c!--[![Version](https://img.shields.io/npm/v/magic-grid.svg?style=for-the-badge)](https://www.npmjs.com/package/magic-grid)--\u003e\n\n# Magic Grid [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Magic%20Grid%20-%20A%20simple,%20lightweight%20Javascript%20library%20for%20dynamic%20grid%20layouts.\u0026url=https://github.com/e-oj/Magic-Grid\u0026hashtags=MagicGrid,GridLayout,JS)\n\n## A simple, lightweight Javascript library for dynamic grid layouts.\n\nCreating a dynamic grid layout has never been easier. With Magic Grid, all you have to do is specify a container and listen for changes. A few other configuration options are available for convenience but it's all very simple. Check it out live \u003cb\u003e[on JSFIDDLE](https://jsfiddle.net/eolaojo/4pov0rdf/)\u003c/b\u003e. You can read about the implementation details \u003cb\u003e[on CodeBurst](https://codeburst.io/magic-grid-f8e2221e7cef)\u003c/b\u003e.\n\n**Note: Every item in the grid must have the same width.**\n\n#### [Sample Usage](https://github.com/e-oj/Magic-Grid/blob/master/test/grid.html)\n\n\u003cimg src=\"https://drive.google.com/u/1/uc?id=1UaszcWA83aaLl0ZPAUtZW4K-qfuyJz7Z\" alt=\"demo\" width=\"850\"\u003e\u003c/img\u003e\n\n### Why not CSS Grid?\n\nThis question is addressed in \u003cb\u003e[the article](https://codeburst.io/magic-grid-f8e2221e7cef)\u003c/b\u003e:\n\n\u003e Implementing a grid layout can quickly turn into a tricky task. If you have grid items that are always the same height, then you can probably make do with a Flexbox grid or some other CSS grid implementation. However, if you’re dealing with user-generated content, chances are, you don’t have the luxury of equal height components. One longer or shorter component would either stretch the other components in its row, or leave some unpleasant whitespace at the bottom of the row. All of a sudden, our beloved CSS grid has become insufficient.\n\nCheck out \u003cb\u003e[CSS Grid AMA's issue #19](https://github.com/rachelandrew/cssgrid-ama/issues/19)\u003c/b\u003e for a response from CSS expert \u003cb\u003e[@rachelandrew](https://github.com/rachelandrew)\u003c/b\u003e:\n\n\u003e That's not something grid is designed for. Grid is two dimensional so you are always working in both rows and columns at the same time. You can't use grid to do a \"masonry\" style layout like that. You could place items in that way if you had a lot of rows and managed how many each spanned, but you can't use auto-placement to get that kind of layout.\n\n\n### Ports\n\n| Repo                                                        | Framework | Authors                                                                                                                                                          |\n|:------------------------------------------------------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| [use-magic-grid](https://github.com/e-oj/use-magic-grid)    | React     | [@e-oj](https://github.com/IniZio) [@Esstar612](https://github.com/Esstar612) [@SujiChen](https://github.com/SujiChen) [@yuguangl](https://github.com/yuguangl)  |\n| [Vue-Magic-Grid](https://github.com/imlinus/Vue-Magic-Grid) | Vue       | [@imlinus](https://github.com/imlinus)                                                                                                                           |\n\n### Getting Started\n#### Step 1\n\nGet Magic Grid via NPM:\n\n```\nnpm install magic-grid\n```\n\nOr CDN\n```html\n\u003cscript src=\"https://unpkg.com/magic-grid/dist/magic-grid.cjs.js\"\u003e\u003c/script\u003e\n\n\u003c!-- or (minified) --\u003e\n\u003cscript src=\"https://unpkg.com/magic-grid/dist/magic-grid.min.js\"\u003e\u003c/script\u003e\n```\n\n#### Step 2 (skip if using CDN)\n\nImport Magic Grid:\n\n```javascript\nimport MagicGrid from \"magic-grid\"\n\n// or\nlet MagicGrid = require(\"magic-grid\");\n```\n\u003cbr\u003e\n\nYou can also pull Magic Grid directly into your html\n\n```html\n\u003cscript src=\"node_modules/magic-grid/dist/magic-grid.min.js\"\u003e\u003c/script\u003e\n```\n\n#### Step 3\n\nYou're good to go! If you used a script tag, the library can be referenced via the global variable, MagicGrid.\n\n```javascript\nlet magicGrid = new MagicGrid(...);\n\nmagicGrid.listen();\n```\n\n### Usage\n#### Static content:\nIf your container doesn't have any dynamically loaded content i.e., all its child elements are always in the DOM, you should initialize the grid this way:\n```javascript\nlet magicGrid = new MagicGrid({\n  container: \"#container\", // Required. Can be a class, id, or an HTMLElement.\n  static: true, // Required for static content.\n  animate: true, // Optional.\n});\n\nmagicGrid.listen();\n```\n\n#### Dynamic content:\nIf the container relies on data from an api, or experiences a delay, for whatever reason, before it can render its content in the DOM, you need to let the grid know the number of items to expect:\n```javascript\nlet magicGrid = new MagicGrid({\n  container: \"#container\", // Required. Can be a class, id, or an HTMLElement.\n  items: 20, // For a grid with 20 items. Required for dynamic content.\n  animate: true, // Optional.\n});\n\nmagicGrid.listen();\n```\n\n### API\n\n#### MagicGrid(config)\n \u003e config (required): Configuration object\n\nThe MagicGrid constructor. Initializes the grid with a configuration object.\n```javascript\nlet magicGrid = new MagicGrid({\n  container: \"#container\", // Required. Can be a class, id, or an HTMLElement\n  static: false, // Required for static content. Default: false.\n  items: 30, // Required for dynamic content. Initial number of items in the container.\n  gutter: 30, // Optional. Space between items. Default: 25(px).\n  maxColumns: 5, // Optional. Maximum number of columns. Default: Infinite.\n  useMin: true, // Optional. Prioritize shorter columns when positioning items? Default: false.\n  useTransform: true, // Optional. Position items using CSS transform? Default: True.\n  animate: true, // Optional. Animate item positioning? Default: false.\n  center: true, //Optional. Center the grid items? Default: true. \n});\n```\n\n---\n\n#### .listen()\nPositions the items and listens for changes to the window size. All items are repositioned whenever the window is resized.\n```javascript\nlet magicGrid = new MagicGrid({\n  container: \"#container\", // Required. Can be a class, id, or an HTMLElement\n  static: true, // Required for static content.\n  animate: true, // Optional.\n});\n\nmagicGrid.listen();\n```\n\n#### Magic grid will also listen for changes in container size\n\u003ca href=\"https://drive.google.com/file/d/1iKCvlUIkxpXJFmNpV0FiEW5YECrIw14K/view\"\u003e\n    \u003cimg src=\"https://drive.google.com/uc?id=1iKCvlUIkxpXJFmNpV0FiEW5YECrIw14K\" alt=\"video thumbnail\" width=\"850\"\u003e\n\u003c/a\u003e\n\n---\n\n#### .positionItems()\nThis function is useful in cases where you have to manually trigger a repositioning; for instance, if a new element is added to the container.\n\n```javascript\nlet magicGrid = new MagicGrid({\n  container: \"#container\", // Required. Can be a class, id, or an HTMLElement\n  items: 30, // Required for dynamic content.\n  animate: true, // Optional\n});\n\nmagicGrid.listen();\n\n// get data from api\n// append new element to DOM\n\n// reposition items\nmagicGrid.positionItems();\n```\n\n---\n\n#### .onReady(callback)\nAdds a listener that executes a function once the grid is ready.\n\n```javascript\nconst magicGrid = new MagicGrid({\n  container: '.container', // Required. Can be a class, id, or an HTMLElement\n  animate: true, // Optional\n  static: true, // Required for static content.\n});\n\nconst id = magicGrid.onReady(() =\u003e {\n  console.log(\"Grid is ready\");\n});\n\nmagicGrid.listen();\n```\n\n---\n\n#### .onPositionComplete(callback)\nAdds a listener that executes a function whenever `positionItems` is called. \n**Note: `positionItems` is called during initial setup and whenever the container or window is resized**\n\n```javascript\nconst magicGrid = new MagicGrid({\n  container: '.container', // Required. Can be a class, id, or an HTMLElement\n  animate: true, // Optional\n  static: true, // Required for static content.\n});\n\nconst id = magicGrid.onPositionComplete(() =\u003e {\n  console.log(\"Grid Has Been Resized\"); // Example function\n});\n\nmagicGrid.listen();\n```\n\n---\n\n#### .removeListener(id)\nAllows the removal of any listener by its unique ID.\n\n```javascript\nconst magicGrid = new MagicGrid({\n  container: '.container', // Required. Can be a class, id, or an HTMLElement\n  animate: true, // Optional\n  static: true, // Required for static content.\n});\n\nconst id = magicGrid.onPositionComplete(() =\u003e {\n  console.log(\"Grid Has Been Resized\"); \n  magicGrid.removeListener(id); // remove callback listener\n});\n\nmagicGrid.listen();\n```\n\n---\n","funding_links":[],"categories":["JavaScript","📦 Legacy \u0026 Inactive Projects","目录","Programming Languages","Côté client, Frontend"],"sub_categories":["JavaScript","JS"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe-oj%2FMagic-Grid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fe-oj%2FMagic-Grid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe-oj%2FMagic-Grid/lists"}