React 데이터 그리드 구현: Wijmo FlexGrid JSX 컴포넌트 가이드
React로 관리자 화면이나 대시보드를 만들다 보면 수천 행을 빠르게 렌더링하면서 정렬·필터·편집까지 되는 데이터 그리드가 필요해집니다. Wijmo FlexGrid는 JSX 선언형 문법과 TypeScript 타입 지원을 함께 제공해, 직접 테이블을 구현하는 부담을 줄여 줍니다. @mescius/wijmo.react.grid
패키지는 순수 JavaScript FlexGrid의 성능을 그대로 유지하면서 React 컴포넌트 트리에 자연스럽게 통합되며, React 19의 concurrent rendering 환경에서도 안정적으로 동작합니다.
이 글에서는 패키지 설치부터 컬럼 정의, 커스텀 셀 렌더링까지 처음 React 그리드를 만드는 개발자가 바로 따라 할 수 있도록 예제를 단계별로 완성합니다.
@mescius/wijmo.react.grid
로 React 그리드를 만드는 3가지 핵심 컴포넌트: FlexGrid
, FlexGridColumn
, FlexGridCellTemplate
autoGenerateColumns={false}
와 FlexGridColumn
자식 컴포넌트로 표시할 컬럼을 직접 지정하는 방법FlexGridCellTemplate
의 cellType
속성으로 셀·헤더·행 헤더에 원하는 JSX를 렌더링하는 방법initialized
이벤트로 마운트 직후 FlexGrid 인스턴스를 받아 코드로 제어하는 방법'use client'
디렉티브로 그리드를 클라이언트 컴포넌트로 지정하는 방법React 프로젝트에 Wijmo 그리드 패키지 설치하고 CSS 적용하기
@mescius/wijmo.react.all
단일 패키지로 모든 Wijmo React 컴포넌트를 일괄 설치할 수 있습니다. FlexGrid만 필요하다면 그리드 전용 패키지만 설치해 번들 크기를 줄일 수도 있습니다.
전체 React 번들 설치 (권장):
FlexGrid 전용 설치:
설치 후 애플리케이션 루트 파일( index.tsx
또는 main.tsx
)에서 Wijmo 스타일시트를 한 번 import합니다. 이 CSS는 모든 Wijmo 컴포넌트에 공통으로 적용되므로 루트에서 한 번만 선언하면 됩니다.
예제 1: FlexGridColumn으로 React 기본 그리드 만들기
FlexGrid React 컴포넌트를 사용할 때 가장 중요한 패턴이 있습니다. autoGenerateColumns={false}
프로퍼티를 먼저 선언해 자동 컬럼 생성을 막고, FlexGridColumn
자식 컴포넌트로 각 컬럼을 명시적으로 정의한 후, 마지막으로 itemsSource
에 데이터를 연결하는 순서입니다. 이 순서를 지키지 않으면 그리드가 데이터 구조를 먼저 읽어 자동 생성 컬럼과 명시 컬럼이 중복되는 문제가 발생합니다.
STEP 1: 기본 FlexGrid 컴포넌트 작성하기
@mescius/wijmo.react.grid
에서 컴포넌트를 임포트하고, 직원 데이터를 바인딩하는 기본 그리드를 구성합니다. FlexGridColumn
의 binding
은 데이터 필드명, format
은 숫자·날짜 서식 문자열을 지정합니다.
STEP 2: 완성 — 입사일·재직 컬럼과 행 선택 모드 추가하기
나머지 컬럼을 추가하고 selectionMode="Row"
로 행 단위 선택을 활성화합니다. isReadOnly={true}
로 셀 편집을 비활성화해 조회 전용 그리드로 완성합니다. 아래 라이브 데모는 CodePen(번들러 없음) 환경에서 실행하기 위해 @mescius/wijmo.react.grid
래퍼 대신 Wijmo 코어 API를 React Hooks로 감싼 형태로 작성했습니다 — columns
/ selectionMode
/ isReadOnly
등 옵션은 위 JSX 래퍼 props와 동일하게 매핑되므로, 실제 프로젝트에서는 STEP 1처럼 JSX 래퍼 컴포넌트를 그대로 사용하면 됩니다.
위 라이브 데모에서 행을 클릭하면 행 단위로 하이라이트되고, 더블 클릭해도 편집 모드로 진입하지 않는 것을 확인할 수 있습니다. format: 'n0'
은 숫자를 천 단위 구분자 포함 정수로, format: 'yyyy-MM-dd'
는 날짜를 ISO 형식으로 표시합니다.
예제 2: FlexGridCellTemplate으로 React 커스텀 셀 만들기
FlexGridCellTemplate
컴포넌트는 셀의 표시 방식을 React JSX로 완전히 제어할 수 있게 해 줍니다. cellType
속성 값에 따라 적용 대상이 결정되며, 배치 규칙이 있습니다. 컬럼별 셀 템플릿은 해당 FlexGridColumn
의 자식으로 선언하고, 그리드 전체 수준 템플릿(행 헤더, 좌상단 코너 등)은 FlexGrid
의 직속 자식으로 선언합니다.
cellType
이 지원하는 주요 값을 정리하면 다음과 같습니다:
template
render prop은 context
객체를 받으며, context.item
으로 해당 행의 데이터, context.col
로 컬럼 객체, context.row
로 행 객체에 접근합니다.
STEP 1: 행 번호 RowHeader와 재직 상태 배지 셀 템플릿 작성하기
행 헤더에 순번을 표시하고, 재직 컬럼에 색상 배지를 렌더링합니다. RowHeader
템플릿은 FlexGrid
의 직속 자식으로, Cell
템플릿은 FlexGridColumn
의 자식으로 각각 배치합니다.
STEP 2: 완성 — 연봉 헤더 아이콘과 고연봉 셀 강조 추가하기
ColumnHeader
템플릿으로 연봉 헤더에 ₩ 아이콘을 추가하고, Cell
템플릿으로 90,000 이상인 연봉을 파란색으로 강조한 최종 완성 코드입니다. 아래 라이브 데모는 CodePen(번들러 없음) 환경에서 실행하기 위해 FlexGridCellTemplate
JSX 대신, 코어 API의 formatItem
이벤트로 동일한 셀 커스터마이징을 구현했습니다 — e.panel
로 RowHeader/ColumnHeader/Cell 영역을 구분하는 방식이며, 실제 프로젝트에서는 STEP 1처럼 FlexGridCellTemplate
JSX 컴포넌트를 그대로 사용하면 됩니다.
위 라이브 데모에서 행 헤더의 순번, 연봉 헤더의 ₩ 아이콘, 91,000인 박지호 행의 파란색 강조, 재직 상태 배지를 확인할 수 있습니다.
initialized 이벤트로 그리드 인스턴스에 접근하기
initialized
이벤트는 FlexGrid가 DOM에 마운트된 직후 한 번 발생합니다. sender
파라미터로 전달되는 FlexGrid 코어 인스턴스를 useState
에 저장해 두면, 이후 버튼 클릭이나 외부 이벤트에서도 그리드를 프로그래밍 방식으로 제어할 수 있습니다.
initialized
핸들러 시그니처는 일반적으로 (sender, args)
형태이지만, 이 이벤트는 초기화 완료 시 한 번만 발생하므로 실무에서는 sender
만 사용하는 경우가 대부분입니다. sender.autoSizeColumn(0)
처럼 초기 레이아웃 조정 코드를 여기에 배치하면 useEffect
없이도 그리드 마운트 시점을 정확히 포착할 수 있습니다.
Next.js App Router에서 Wijmo FlexGrid 적용하기
Next.js 13+ App Router 환경에서 Wijmo FlexGrid는 브라우저 DOM에 직접 접근하는 클라이언트 사이드 라이브러리이므로, 서버 컴포넌트에서는 동작하지 않습니다. 그리드를 사용하는 파일 최상단에 'use client'
를 반드시 선언해야 합니다.
서버 컴포넌트에서 데이터를 fetch하고 클라이언트 컴포넌트에 props로 전달하는 패턴이 권장됩니다:
이 패턴은 데이터 fetch를 서버에서 처리해 클라이언트 번들에 fetch 로직이 포함되지 않고, Wijmo 그리드는 클라이언트에서만 렌더링되어 SSR 관련 오류를 방지합니다.
자주 묻는 질문 (FAQ)
React에서 데이터 그리드를 가장 빠르게 만드는 방법은?
npm install @mescius/wijmo.react.all
로 패키지를 설치한 후, import * as wjGrid from '@mescius/wijmo.react.grid'
로 임포트합니다. 루트 파일에서 import '@mescius/wijmo.styles/wijmo.css'
를 한 번 선언하고, JSX에서 <wjGrid.FlexGrid autoGenerateColumns={false} itemsSource={data}>
형태로 사용합니다. FlexGridColumn
자식 컴포넌트로 컬럼을 정의하며, 순수 JavaScript FlexGrid의 모든 프로퍼티와 이벤트를 JSX props로 동일하게 사용할 수 있습니다.React 그리드 컴포넌트는 어떤 구성 요소로 이루어져 있나요?
@mescius/wijmo.react.grid
는 FlexGrid
(그리드 루트), FlexGridColumn
(컬럼 정의), FlexGridCellTemplate
(커스텀 셀 렌더링) 세 가지 핵심 컴포넌트로 구성됩니다. autoGenerateColumns={false}
설정 후 FlexGridColumn
을 자식으로 추가하는 선언형 방식이 권장되며, columns
prop에 배열을 직접 전달하는 방식도 지원합니다. 두 방식 모두 itemsSource
연결 전에 컬럼을 정의해야 합니다.React 그리드 셀에 커스텀 JSX를 렌더링하려면 어떻게 하나요?
FlexGridColumn
자식으로 <FlexGridCellTemplate cellType="Cell" template={(context) => <JSX />} />
를 선언합니다. template
render prop의 context
객체는 col
(컬럼), row
(행), item
(데이터 항목) 세 가지 속성을 제공합니다. 행 헤더나 TopLeft처럼 특정 컬럼과 무관한 템플릿은 FlexGrid
의 직속 자식으로 선언해야 하며, FlexGridColumn
자식에 배치하면 동작하지 않습니다.Wijmo FlexGrid와 AG Grid React 중 어느 것이 기업용으로 더 적합한가?
TypeScript로 React 그리드를 타입 안전하게 사용하려면 어떻게 하나요?
.d.ts
)이 기본 포함되어 있습니다. FlexGrid
인스턴스 타입은 @mescius/wijmo.grid
에서 import type * as wjcGrid from '@mescius/wijmo.grid'
로 임포트한 wjcGrid.FlexGrid
로 완전한 타입 추론이 지원됩니다. initialized
이벤트 핸들러에서 sender: wjcGrid.FlexGrid
로 타입을 지정하면 IDE 자동완성으로 autoSizeColumn
, select
, collectionView
등 모든 API를 탐색할 수 있습니다.
