React Grid Plus

A high-performance, flexible grid component for rendering large lists of items efficiently.

Key Features

• Responsive Columns: Automatically adjusts grid layout (2-6 columns)
• Flexible Spacing: Configurable gap sizes for item spacing
• Dual Scroll Modes: Support for both vertical and horizontal scrolling
• Pagination Support: Show limited items with a "view more" footer
• Loading States: Built-in loading component display
• Type-Safe: Full TypeScript support with generic types
• Tailwind CSS: Uses Tailwind utility classes for styling

Installation

npm install @mostafa-ashour-dev/react-grid-plus

Usage

Basic Example

import { Grid } from '@mostafa-ashour-dev/react-grid-plus';

interface Item {
  id: number;
  title: string;
  description: string;
}

const items: Item[] = [
  { id: 1, title: 'Item 1', description: 'Description 1' },
  { id: 2, title: 'Item 2', description: 'Description 2' },
  // ... more items
];

export default function MyComponent() {
  return (
    <Grid<Item>
      data={items}
      cols={3}
      gap={4}
      renderItem={(item) => (
        <div key={item.id} className="p-4 border rounded">
          <h3>{item.title}</h3>
          <p>{item.description}</p>
        </div>
      )}
    />
  );
}

Advanced Example with Scrolling

<Grid<Item>
  data={items}
  cols={4}
  gap={2}
  scrollable={true}
  scrollDir="horizontal"
  scrollFit={true}
  maxItems={12}
  footer={{ text: 'View All Items', href: '/all-items' }}
  renderItem={(item, index) => (
    <div key={item.id}>
      <h3>{item.title}</h3>
    </div>
  )}
/>

Props

Prop	Type	Default	Description
data	T[]	undefined	Array of items to render in the grid. Can be any data type.
renderItem	(item: T, index: number) => React.ReactNode	Required	Function that renders each item. Receives the item and its index.
cols	number	3	Number of columns in the grid. Supports values 2-6. Applies Tailwind grid-cols-{n} classes.
gap	number	4	Spacing between grid items. Supports values 2, 4, 5, 6. Applies Tailwind gap-{n} classes.
scrollable	boolean	false	Enables scrolling behavior. When true, combined with scrollDir to determine scroll direction.
scrollDir	"vertical" | "horizontal"	"horizontal"	Direction of scrolling. Use "vertical" for vertical scroll or "horizontal" for horizontal scroll.
scrollFit	boolean	false	Applies overflow and size constraints based on the tallest/widest item. Works with scrollDir for responsive sizing.
maxItems	number	undefined	Maximum number of items to display. If set and data.length exceeds this, a footer link is shown.
footer	{ text: string; href: string }	undefined	Custom footer link configuration. If not provided, defaults to "View {count} more" text.
hideFooter	boolean	false	Hides the footer link even when maxItems is set and items exceed the limit.
loading	boolean	false	Shows the loading component when true. Useful for data loading states.
loadingComponent	React.ReactNode	<span>Loading...</span>	Custom component to display while loading. Only shown when loading is true.
className	string	""	Additional Tailwind CSS classes to apply to the grid container.