CatalogFrame

Shell

Compose catalog headers, statistics, notices, filters, inspectors, pagination, bulk actions, and empty or error states; clear selection when filters or pages change.

Related docs

bun add @reopt-ai/opt-ui

Install and import

bash

bun add @reopt-ai/opt-ui

tsx

import { CatalogFrame, CatalogRowActions, CatalogCellControls } from "@reopt-ai/opt-ui";

Live preview

Change the width and theme, then interact with the components.

100%

목록과 그 옆에서 읽는 한 건

이벤트	상태	볼륨
purchase_completed	활성	1,284
signup_completed	활성	412
legacy_ping	보관	3

Usage guidance

Best practices

Build catalog-style list screens by adding column definitions and labels to this frame.
The host owns queries and filtering. When query changes, filter local data again or request server data, then calculate isEmpty from the result.
Connect page, totalCount, and onPageChange for server lists. Provide selectedKeys with onSelectionChange so selection resets can be reflected when filters or pages change.
Report query failures through error and onRetry, keeping them distinct from valid empty results. Use emptyActions for the next action when there are no filters.

Usage to avoid

Do not leave selection reset as an implicit responsibility of callers; otherwise bulk actions may affect hidden rows.

Usage examples

Connect search, selection, and details in a local list

CatalogFrame

Prop	Type	Default	Description
childrenRequired	ReactNode	—	테이블. 빈/에러 상태에서는 대체됨
isEmptyRequired	boolean	—	테이블이 0행인지
queryRequired	Query	—	필터 상태
onQueryChangeRequired	(query: Query) => void	—	Query 변경
filters	QueryFilterDef[]	—	필터 정의
stats	StatCardType[]	—	통계 카드
onStatClick	(stat: StatCardType) => void	—	카드 클릭 = 필터
notice	ReactNode	—	목록 위 고지
emptyActions	ReactNode	—	필터 없는 빈 상태의 다음 행동 (필터된 빈 상태는 필터 지우기 유지)
header	ReactNode	—	헤더 슬롯
actions	ReactNode	—	액션 슬롯
toolbar	ReactNode	—	통계와 필터 사이 컨트롤 (스코프 세그먼트 등)
inspector	ReactNode	—	인스펙터 내용
inspectorOpenRequired	boolean	—	인스펙터 열림
onInspectorCloseRequired	() => void	—	인스펙터 닫기
inspectorTitle	ReactNode	—	인스펙터 제목
inspectorDescription	ReactNode	—	인스펙터 설명
inspectorActions	ReactNode	—	인스펙터 헤더 컨트롤
inspectorFooter	ReactNode	—	인스펙터 하단
inspectorWidth	"sm" \| "md" \| "lg"	—	push 레이아웃 폭
page	number	1	현재 페이지
pageSize	number	50	페이지 크기
totalCount	number	—	필터 반영 총 개수
onPageChange	(page: number) => void	—	페이지 변경
selectedKeys	string[]	—	선택된 행
onSelectionChange	(keys: string[]) => void	—	선택 변경. 필터·페이지가 바뀌면 프레임이 비웁니다
bulkActions	FloatingAction[]	—	일괄 작업
onBulkAction	(actionId: string) => void	—	일괄 작업 실행
error	ReactNode	—	읽기 실패. 빈 목록과 다른 답
onRetry	() => void	—	재시도
labels	CatalogFrameLabels	—	빈/필터된 빈/에러 문구와 인스펙터 닫기 버튼(closeInspector)
className	string	—	추가 CSS 클래스

CatalogRowActions

Prop	Type	Default	Description
itemRequired	T	—	이 행의 항목
actionsRequired	CatalogRowAction<T>[]	—	행 액션
visibleCount	number	2	오버플로 전에 노출할 개수. available 필터링 후에 적용됨
labels	CatalogRowActionsLabels	—	그룹·오버플로 라벨

CatalogRowAction

Prop	Type	Default	Description
idRequired	string	—	액션 키
labelRequired	string	—	액션 문구
icon	ReactNode	—	선택적 액션 아이콘
onSelectRequired	(item: T) => void	—	행과 함께 호출되는 액션
available	(item: T) => boolean	—	이 행에 적용되지 않는 액션을 비활성화 대신 제거

CatalogCellControls

Prop	Type	Default	Description
childrenRequired	ReactNode	—	행 클릭으로 새면 안 되는 셀 컨트롤

View test results

테스트 커버리지

2026년 7월 9일

생성된 테스트 결과를 찾지 못했습니다.

CatalogFrame 항목이 문서 메타에 연결되어 있지만 현재 생성 파일에는 없습니다.

테스트를 추가한 뒤 `bun run generate:test-results`를 실행하거나 `testDescribe` 매핑을 다시 확인하세요.

Related components

FaqAccordion

Shells

Organize FAQ questions and answers with Composite and Disclosure components.

PageAside

Shells

Add a sticky, fixed-width page aside with header, body, and footer slots.

EnvPanel

Shells

Browse environment variables with collapsible environment groups and Composite navigation.

BranchSelect

Shells

Choose a Git branch with a wrapper around the Select primitive.

DesignGuidePanel

Shells

Consult six design-system reference sections covering primitives, keyboard patterns, Tailwind selectors, and accessibility attributes.

QuickActions

Shells

Present frequent actions in a grid or list with keyboard shortcut labels.

CatalogFrame

Shell

Compose catalog headers, statistics, notices, filters, inspectors, pagination, bulk actions, and empty or error states; clear selection when filters or pages change.

Related docs

bun add @reopt-ai/opt-ui

Install and import

bash

bun add @reopt-ai/opt-ui

tsx

import { CatalogFrame, CatalogRowActions, CatalogCellControls } from "@reopt-ai/opt-ui";

Live preview

Change the width and theme, then interact with the components.

100%

목록과 그 옆에서 읽는 한 건

이벤트	상태	볼륨
purchase_completed	활성	1,284
signup_completed	활성	412
legacy_ping	보관	3

Usage guidance

Best practices

Build catalog-style list screens by adding column definitions and labels to this frame.
The host owns queries and filtering. When query changes, filter local data again or request server data, then calculate isEmpty from the result.
Connect page, totalCount, and onPageChange for server lists. Provide selectedKeys with onSelectionChange so selection resets can be reflected when filters or pages change.
Report query failures through error and onRetry, keeping them distinct from valid empty results. Use emptyActions for the next action when there are no filters.

Usage to avoid

Do not leave selection reset as an implicit responsibility of callers; otherwise bulk actions may affect hidden rows.

Usage examples

Connect search, selection, and details in a local list

CatalogFrame

Prop	Type	Default	Description
childrenRequired	ReactNode	—	테이블. 빈/에러 상태에서는 대체됨
isEmptyRequired	boolean	—	테이블이 0행인지
queryRequired	Query	—	필터 상태
onQueryChangeRequired	(query: Query) => void	—	Query 변경
filters	QueryFilterDef[]	—	필터 정의
stats	StatCardType[]	—	통계 카드
onStatClick	(stat: StatCardType) => void	—	카드 클릭 = 필터
notice	ReactNode	—	목록 위 고지
emptyActions	ReactNode	—	필터 없는 빈 상태의 다음 행동 (필터된 빈 상태는 필터 지우기 유지)
header	ReactNode	—	헤더 슬롯
actions	ReactNode	—	액션 슬롯
toolbar	ReactNode	—	통계와 필터 사이 컨트롤 (스코프 세그먼트 등)
inspector	ReactNode	—	인스펙터 내용
inspectorOpenRequired	boolean	—	인스펙터 열림
onInspectorCloseRequired	() => void	—	인스펙터 닫기
inspectorTitle	ReactNode	—	인스펙터 제목
inspectorDescription	ReactNode	—	인스펙터 설명
inspectorActions	ReactNode	—	인스펙터 헤더 컨트롤
inspectorFooter	ReactNode	—	인스펙터 하단
inspectorWidth	"sm" \| "md" \| "lg"	—	push 레이아웃 폭
page	number	1	현재 페이지
pageSize	number	50	페이지 크기
totalCount	number	—	필터 반영 총 개수
onPageChange	(page: number) => void	—	페이지 변경
selectedKeys	string[]	—	선택된 행
onSelectionChange	(keys: string[]) => void	—	선택 변경. 필터·페이지가 바뀌면 프레임이 비웁니다
bulkActions	FloatingAction[]	—	일괄 작업
onBulkAction	(actionId: string) => void	—	일괄 작업 실행
error	ReactNode	—	읽기 실패. 빈 목록과 다른 답
onRetry	() => void	—	재시도
labels	CatalogFrameLabels	—	빈/필터된 빈/에러 문구와 인스펙터 닫기 버튼(closeInspector)
className	string	—	추가 CSS 클래스

CatalogRowActions

Prop	Type	Default	Description
itemRequired	T	—	이 행의 항목
actionsRequired	CatalogRowAction<T>[]	—	행 액션
visibleCount	number	2	오버플로 전에 노출할 개수. available 필터링 후에 적용됨
labels	CatalogRowActionsLabels	—	그룹·오버플로 라벨

CatalogRowAction

Prop	Type	Default	Description
idRequired	string	—	액션 키
labelRequired	string	—	액션 문구
icon	ReactNode	—	선택적 액션 아이콘
onSelectRequired	(item: T) => void	—	행과 함께 호출되는 액션
available	(item: T) => boolean	—	이 행에 적용되지 않는 액션을 비활성화 대신 제거