{"id":13632227,"url":"https://github.com/askides/react-plock","last_synced_at":"2025-05-14T21:08:54.023Z","repository":{"id":39789369,"uuid":"446514036","full_name":"askides/react-plock","owner":"askides","description":"The 1kB Masonry Grid for React.","archived":false,"fork":false,"pushed_at":"2025-03-06T08:32:41.000Z","size":1698,"stargazers_count":552,"open_issues_count":0,"forks_count":13,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-25T15:09:16.825Z","etag":null,"topics":["masonry","masonry-layout","nextjs","react"],"latest_commit_sha":null,"homepage":"https://react-plock-with-nextjs.vercel.app","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/askides.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-10T17:11:49.000Z","updated_at":"2025-04-24T01:02:32.000Z","dependencies_parsed_at":"2024-01-22T01:13:52.381Z","dependency_job_id":"201606f1-da4e-4d5c-a3d8-158748144e58","html_url":"https://github.com/askides/react-plock","commit_stats":null,"previous_names":["itsrennyman/react-plock"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/askides%2Freact-plock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/askides%2Freact-plock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/askides%2Freact-plock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/askides%2Freact-plock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/askides","download_url":"https://codeload.github.com/askides/react-plock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250840609,"owners_count":21495910,"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":["masonry","masonry-layout","nextjs","react"],"created_at":"2024-08-01T22:02:56.893Z","updated_at":"2025-04-25T15:09:25.191Z","avatar_url":"https://github.com/askides.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"![Plock Logo](./assets/cover.png)\n\nReact Plock is a tree-shakeable **ultra small** npm package (**less than 1kB gzipped**) that allows you to create amazing masonry layouts with an amazing developer experience. With React Plock, you can easily create responsive and customizable layouts that adapt to different screen sizes and devices.\n\n### Features\n\n- **Masonry Layout**: Create beautiful masonry layouts with ease.\n- **Balanced Layout**: Create a more visually harmonious masonry grid by considering the height of each item.\n- **Responsive**: Automatically adapts to different screen sizes and devices.\n- **Customizable**: Customize the layout to match your needs.\n- **TypeScript Ready**: Get the strength of type-safe languages.\n- **Amazing DX**: Easy to use and well-documented.\n\n### Examples\n\n- Using Next.js 14 (Server Components) [See Working Demo](https://react-plock-with-nextjs.vercel.app/)\n- Using ViteJS [See Working Demo](https://react-plock-with-vite.vercel.app/)\n\n### Installation\n\n```bash\nnpm install react-plock\n```\n\n### Usage\n\nUsing Plock with the new v3 APIs it's a piece of cake. Here's an example of how can you create a masonry grid. You can even see a demo of this example by clicking [here](https://react-plock-with-vite.vercel.app/).\n\n```tsx\nimport { Masonry } from 'react-plock';\n\nconst ImagesMasonry = () =\u003e {\n  const items = [...imageUrls];\n\n  return (\n    \u003cMasonry\n      items={items}\n      config={{\n        columns: [1, 2, 3],\n        gap: [24, 12, 6],\n        media: [640, 768, 1024],\n      }}\n      render={(item, idx) =\u003e (\n        \u003cimg key={idx} src={item} style={{ width: '100%', height: 'auto' }} /\u003e\n      )}\n    /\u003e\n  );\n};\n```\n\n### Balanced Layout\n\nReact Plock offers a balanced layout option that creates a more visually harmonious masonry grid by considering the height of each item. When enabled with `useBalancedLayout: true`, the layout algorithm distributes items across columns while attempting to minimize height differences between columns.\n\nThis is particularly useful for content with varying heights, such as images or cards, where a traditional masonry layout might create uneven columns.\n\nUnlike the default layout which distributes items sequentially, the balanced layout dynamically measures and adjusts item placement to create a more aesthetically pleasing result.\n\n```tsx\n\u003cMasonry\n  items={items}\n  config={{\n    columns: [2, 3, 4],\n    gap: [16, 16, 16],\n    media: [640, 768, 1024],\n    useBalancedLayout: true, // Enable balanced layout\n  }}\n  render={(item) =\u003e (\n    \u003cimg src={item.url} alt={item.alt} style={{ width: '100%' }} /\u003e\n  )}\n/\u003e\n```\n\n### API Reference\n\nHere's the TypeScript definition for the Masonry Component, below you can find a more detailed explanation.\n\n```ts\nexport type MasonryProps\u003cT\u003e = React.ComponentPropsWithoutRef\u003c'div'\u003e \u0026 {\n  items: T[];\n  render: (item: T, idx: number) =\u003e React.ReactNode;\n  config: {\n    columns: number | number[];\n    gap: number | number[];\n    media?: number[];\n    useBalancedLayout?: boolean;\n  };\n  as?: React.ElementType;\n};\n```\n\n#### Items\n\nThis prop accepts a generic array of elements, each one will be passed to the **render** property.\n\n#### Render\n\nThe masonry render prop. Here's where you define the styles of every tile of the grid, the function takes the current looping item and the relative index.\n\n#### Config\n\nA configuration object that is used to define the number of columns, media queries and gaps between items.\n\n#### Other Props\n\nAs you can see, by using `React.ComponentPropsWithoutRef\u003c\"div\"\u003e` you can simply pass every available property to the div, some examples are **id** and **className**. The only one property that will be overwritten will be the `style` because is used internally for the masonry generation.\n\n### Important Note\n\nPlease, note that in case you are passing an array to the columns attribute of the config property, the number of elements **MUST** be equal to the number of media AND gap breakpoints provided!\n\n```tsx\n// Correct: This will be responsive with 3 breakpoints.\n\u003cMasonry\n  {...otherProps}\n  config={{\n    columns: [1, 2, 3],\n    gap: [12, 16, 20],\n    media: [640, 768, 1024],\n  }}\n/\u003e\n\n// Correct: This will be responsive with 2 breakpoints.\n\u003cMasonry\n  {...otherProps}\n  config={{\n    columns: [1, 2],\n    gap: [2, 4],\n    media: [640, 1024],\n  }}\n/\u003e\n\n// Correct: This will be fixed with 4 columns in every screen size.\n\u003cMasonry\n  {...otherProps}\n  config={{\n    columns: 4,\n    gap: 8\n  }}\n/\u003e\n\n// NOT Correct: This will cause trouble in rendering.\n\u003cMasonry\n  {...otherProps}\n  config={{\n    columns: [4],\n    media: [640, 768],\n  }}\n/\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faskides%2Freact-plock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faskides%2Freact-plock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faskides%2Freact-plock/lists"}