Personalize Bento Grid 🍱

A responsive, interactive grid system for React that supports smooth animations, drag-and-drop, dynamic layout reordering, and variable row/column spans. Bento Grid makes it easy to create modern dashboards and responsive interfaces with minimal configuration.

Table of Contents

• Overview
• Features
• Installation
• Usage
  • Basic Usage
  • Advanced Examples
• API Reference
  • BentoGrid
  • BentoItem
• Customization
• FAQs

Overview

Personalize Bento Grid is a React component package that provides an easy-to-use, highly customizable grid layout system. It leverages CSS Grid along with Framer Motion for smooth animations and drag-and-drop support. With Bento Grid, you can build responsive, modern layouts without writing complicated CSS.

Features

• 🖥️ Responsive Layouts - Configure breakpoints for dynamic column counts and maximum row spans.
• 🎭 Smooth Animations - Built-in animations on mount, exit, and while interacting with grid items.
• 🕹️ Drag & Drop - Optional drag-and-drop functionality for reordering grid items.
• 📱 Touch Friendly - Mobile-first approach
• 🧩 Flexible Items - Control the size of each item with colSpan and rowSpan.
• 🎨 Custom Styling - Styled using styled-components; easily override styles with your own CSS.
• 📐 Priority Sorting - Automatically sort grid items based on priority.
• ⚡ TypeScript Ready - Fully typed for robust development.

Installation

Install the package along with its peer dependencies:

npm install personalize-bento-grid

Note: Ensure your project is using React 16.8 or higher.

Usage

Basic Usage

Create a responsive grid by providing an array of breakpoints, and add grid items with varying sizes:

import React from 'react';
import { BentoGrid, BentoItem } from 'personalize-bento-grid';

const breakpoints = [
  { minWidth: 0, cols: 2, maxItemRows: 2 },
  { minWidth: 768, cols: 3, maxItemRows: 3 },
  { minWidth: 1024, cols: 4, maxItemRows: 4 },
];

const Dashboard = () => {
  return (
    <BentoGrid breakpoints={breakpoints} gap={16}>
      <BentoItem id="item1" colSpan={1} rowSpan={1}>
        Item 1
      </BentoItem>
      <BentoItem id="item2" colSpan={2} rowSpan={1}>
        Item 2 (spans 2 columns)
      </BentoItem>
      <BentoItem id="item3" colSpan={1} rowSpan={2}>
        Item 3 (spans 2 rows)
      </BentoItem>
      <BentoItem id="item4" colSpan={1} rowSpan={1}>
        Item 4
      </BentoItem>
    </BentoGrid>
  );
};

export default Dashboard;

Advanced Examples

Drag & Drop Grid

Enable drag-and-drop by setting the dragEnabled prop:

<BentoGrid breakpoints={breakpoints} gap={16} dragEnabled>
  <BentoItem id="drag1" colSpan={1} rowSpan={1}>Drag 1</BentoItem>
  <BentoItem id="drag2" colSpan={1} rowSpan={1}>Drag 2</BentoItem>
  <BentoItem id="drag3" colSpan={2} rowSpan={1}>Drag 3</BentoItem>
  <BentoItem id="drag4" colSpan={1} rowSpan={2}>Drag 4</BentoItem>
  <BentoItem id="drag5" colSpan={1} rowSpan={1}>Drag 5</BentoItem>
</BentoGrid>

Animated Grid

Control the animation duration with the animationDuration prop:

<BentoGrid breakpoints={breakpoints} gap={16} animationDuration={0.5}>
  <BentoItem id="anim1" colSpan={2} rowSpan={1}>Animated 1</BentoItem>
  <BentoItem id="anim2" colSpan={1} rowSpan={1}>Animated 2</BentoItem>
  <BentoItem id="anim3" colSpan={1} rowSpan={2}>Animated 3</BentoItem>
  <BentoItem id="anim4" colSpan={2} rowSpan={1}>Animated 4</BentoItem>
</BentoGrid>

Priority Sorted Grid

Each grid item can be assigned a priority. Items with higher priority appear first:

<BentoGrid breakpoints={breakpoints} gap={16}>
  <BentoItem id="p1" colSpan={1} rowSpan={1} priority={10}>P10</BentoItem>
  <BentoItem id="p2" colSpan={1} rowSpan={1} priority={5}>P5</BentoItem>
  <BentoItem id="p3" colSpan={2} rowSpan={1} priority={20}>P20</BentoItem>
  <BentoItem id="p4" colSpan={1} rowSpan={2} priority={15}>P15</BentoItem>
</BentoGrid>

Combined Functionality Grid

A grid that combines responsiveness, drag-and-drop, animations, and priority sorting:

<BentoGrid breakpoints={breakpoints} gap={16} dragEnabled animationDuration={0.4}>
  <BentoItem id="c1" colSpan={1} rowSpan={1} priority={5}>Item 1</BentoItem>
  <BentoItem id="c2" colSpan={2} rowSpan={1} priority={10}>Item 2</BentoItem>
  <BentoItem id="c3" colSpan={1} rowSpan={2} priority={8}>Item 3</BentoItem>
  <BentoItem id="c4" colSpan={1} rowSpan={1} priority={2}>Item 4</BentoItem>
  <BentoItem id="c5" colSpan={1} rowSpan={1} priority={6}>Item 5</BentoItem>
  <BentoItem id="c6" colSpan={2} rowSpan={2} priority={12}>Item 6</BentoItem>
</BentoGrid>

API Reference

BentoGrid

| Prop | Type | Default | Description | |--------------------|-------------------------------|--------------|--------------------------------------------------------------------------------------| | breakpoints | LayoutBreakpoint[] | Required | Array of breakpoint objects { minWidth, cols, maxItemRows } for responsive design. | | gap | number \| string | 16 | Gap between grid items. | | autoFlow | 'row' \| 'column' | 'row' | CSS grid auto-flow direction. | | animationDuration| number | 0.3 | Duration (in seconds) for animations on grid items. | | dragEnabled | boolean | false | Enable drag-and-drop functionality for grid items. | | children | React.ReactNode | Required | Grid items, typically BentoItem components. |

BentoItem

| Prop | Type | Default | Description | |--------------|---------------------|---------|-----------------------------------------------------------------------------------------------| | id | string | Required | Unique identifier for the grid item. | | colSpan | number | 1 | Number of columns the item should span. Must not exceed the current grid's column count. | | rowSpan | number | 1 | Number of rows the item should span. Must not exceed the breakpoint's maxItemRows. | | priority | number | 0 | Priority for sorting; higher values make the item appear earlier in the grid. | | children | React.ReactNode | | The content rendered inside the grid item. |

LayoutBreakpoint

Each breakpoint object should include:

• minWidth: The minimum viewport width for this layout.
• cols: Number of columns at this breakpoint.
• maxItemRows: Maximum row span allowed for grid items at this breakpoint.

Customization

Bento Grid is styled with styled-components. To customize the look and feel:

• Override Styles:
  Use CSS or create a custom styled component that wraps BentoGrid or BentoItem.
• Theming:
  Leverage styled-components’ ThemeProvider to pass theme variables to override colors, gaps, borders, etc.
• Custom Item Content:
  Each BentoItem accepts children—render any custom components or HTML as needed.

FAQs

Q: My grid items are all the same size. How can I fix this?
A: Ensure you’ve set different values for colSpan and rowSpan on your BentoItem components. Also, verify that your grid container’s CSS (especially gridAutoRows) is set to a fixed height (e.g., gridAutoRows: '120px') so that items with rowSpan > 1 will be taller.

Q: How do I enable drag-and-drop?
A: Set the dragEnabled prop on BentoGrid to true. This uses Framer Motion’s drag functionality.

Q: What if the grid doesn’t re-sort items based on priority?
A: Each grid item registers its priority with the context. If items aren’t re-sorted, ensure that you’re not overriding the context provider or mutating props unexpectedly.