Getting Started

This guide is not a feature showcase. It walks through installing the package in an existing React application, loading the required styles, connecting data, and rendering your first grid on the page.

After installation, continue to Basic DataGrid for feature-focused guidance on column configuration and cell rendering.

1. Install the package

Run the following command from the root of your React project.

npm install beautiful-grid

If you use another package manager, run one of the following commands.

pnpm add beautiful-grid
# or
yarn add beautiful-grid

BeautifulGrid is a React component. In a new project, make sure React and React DOM are installed first.

2. Load the Grid styles

Import the distributed CSS once from your application entry point. In a Vite project, this is typically src/main.tsx.

import 'beautiful-grid/style.css';

With the Next.js App Router, add the same import to app/layout.tsx, where global CSS can be loaded. Without this stylesheet, the data may render but headers, cells, and scrollbars will not display correctly.

3. Add your first DataGrid to a page

The following example contains only the minimum wiring needed for a user-list page, without advanced features.

import * as React from 'react';
import {
  BGrid,
  type BGridColumn,
  type BGridDataItem,
} from 'beautiful-grid';

interface User {
  id: string;
  name: string;
  department: string;
}

const columns: BGridColumn<User>[] = [
  { key: 'id', label: 'ID', width: 120 },
  { key: 'name', label: 'Name', width: 160 },
  { key: 'department', label: 'Department', width: 180 },
];

const data: BGridDataItem<User>[] = [
  { values: { id: 'U-001', name: 'Hannah Kim', department: 'Engineering' } },
  { values: { id: 'U-002', name: 'Ethan Lee', department: 'Operations' } },
  { values: { id: 'U-003', name: 'Jamie Park', department: 'Design' } },
];

export default function UsersPage() {
  const containerRef = React.useRef<HTMLDivElement>(null);
  const [size, setSize] = React.useState({ width: 0, height: 0 });

  React.useEffect(() => {
    const container = containerRef.current;
    if (!container) return;

    const updateSize = () => {
      const { width, height } = container.getBoundingClientRect();
      setSize({ width: Math.floor(width), height: Math.floor(height) });
    };

    const resizeObserver = new ResizeObserver(updateSize);
    resizeObserver.observe(container);
    updateSize();

    return () => resizeObserver.disconnect();
  }, []);

  return (
    <main>
      <h1>User List</h1>
      <div
        ref={containerRef}
        style={{ position: 'relative', width: '100%', height: 360, minWidth: 0 }}
      >
        {size.width > 0 && size.height > 0 && (
          <BGrid<User>
            width={size.width}
            height={size.height}
            columns={columns}
            data={data}
            rowKey='id'
          />
        )}
      </div>
    </main>
  );
}

If you use this code as a page component in Next.js, add 'use client'; at the top of the file. It is required because ResizeObserver and React Hooks run in the browser.

4. Understand the wiring

Four values are required to render the first Grid:

Input	Role
columns	Defines which fields to display and their labels and widths.
data	Contains the actual values for each row. Always wrap each domain object in { values: ... }.
rowKey	Identifies a unique field for each row so selection, editing, and focus state can be preserved.
width, height	Provides the Grid’s actual pixel dimensions so it can calculate the virtual-scroll viewport.

For a fixed-size page, you can pass numbers directly, such as width={800} and height={360}. On a responsive page, measure the parent container with ResizeObserver as shown above and pass the result to the Grid.

5. Verify the result

Start the development server and verify the following on the user-list page:

1. The ID, Name, and Department headers and three rows are visible.
2. Resizing the browser also resizes the Grid to fit its parent.
3. The developer console shows no CSS import or ResizeObserver errors.

If the page is empty, first verify that the parent container’s height is not 0. If the Grid looks unstyled, confirm that beautiful-grid/style.css is actually loaded from the application entry point.

6. Next steps

After installation and page integration, continue with the guide that matches your goal:

• Basic columns and cell rendering
• Responsive container integration (DataGridContainer)
• Data and column types
• Cell editing