TagView
화면 상단의 열린 탭 목록을 태그 형태로 보여주고, 클릭·닫기·우클릭 메뉴를 지원하는 탭 네비게이션 컴포넌트
개요
TagView는 화면(메뉴) 단위의 탭 관리에 특화된 컴포넌트입니다. 기존 Tabs 컴포넌트가 콘텐츠 영역 전환에 초점을 맞추는 반면, TagView는 열린 화면 목록을 관리하는 데 적합합니다.
주요 특징
- ✅ 탭 선택/해제: 단일 선택, 재클릭 시 해제
- ✅ Closable: X 버튼으로 탭 닫기 +
onClose콜백 - ✅ 닫기 가드:
onBeforeClose로 닫기 전 확인 (비동기 지원) - ✅ ContextMenu: 우클릭 시 닫기/다른 탭 닫기/모두 닫기 + 커스텀 메뉴 확장
- ✅ Controlled/Uncontrolled:
value또는defaultValue
기본 사용
items 배열로 탭 목록을 정의하고, value/onValueChange로 선택 상태를 관리합니다.
Preview
선택된 탭: dashboard
대시보드
사용자 관리
설정
리포트
닫기 기능 (Closable)
closable prop을 활성화하면 각 탭에 X 버튼이 표시됩니다. onClose에서 탭을 제거합니다.
Preview
열린 탭: 4개
대시보드
사용자 관리
설정
리포트
닫기 가드 (onBeforeClose)
onBeforeClose를 사용하면 닫기 직전에 확인을 물어볼 수 있습니다. false를 반환하면 닫기가 취소됩니다. Promise도 지원합니다.
Preview
"대시보드" 탭은 닫기 전에 확인을 물어봅니다.
대시보드
사용자 관리
설정
리포트
커스텀 컨텍스트 메뉴
contextMenuItems에 팩토리 함수를 전달하면 기본 메뉴에 커스텀 항목을 추가할 수 있습니다. tagViewDefaultContextMenuItems를 import하여 기본 메뉴를 포함시킵니다.
Preview
마지막 액션: (우클릭해 보세요)
대시보드
사용자 관리
설정
리포트
비활성화
disabled prop으로 전체 비활성화하거나, 개별 항목의 disabled로 특정 탭만 비활성화합니다.
Preview
활성 탭
비활성 탭
또 다른 탭
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | TagViewItem[] | [] | 탭 항목 목록 |
value | string | - | 선택된 탭 값 (Controlled) |
defaultValue | string | - | 초기 선택 탭 값 (Uncontrolled) |
disabled | boolean | false | 전체 비활성화 |
closable | boolean | false | 닫기(X) 버튼 표시 여부 |
visible | boolean | true | 표시 여부 |
contextMenuItems | ContextMenuItem[] | TagViewContextMenuFactory | - | 커스텀 컨텍스트 메뉴 (배열: 기본 대체, 팩토리: 자유 구성) |
className | string | - | 추가 CSS 클래스 |
aria-label | string | - | 접근성 레이블 |
Events
| Event | Type | Description |
|---|---|---|
onValueChange | (value: string | undefined) => void | 선택 탭 변경 시 호출 |
onBeforeClose | (value: string) => boolean | Promise<boolean> | 닫기 직전 가드 (false 반환 시 닫기 취소) |
onClose | (value: string) => void | 탭 닫기 시 호출 (onBeforeClose 통과 후) |
onContextMenuSelect | (menuItemKey: string, tabValue: string) => void | 컨텍스트 메뉴 항목 클릭 시 호출 |
TagViewItem Data Type
| Property | Type | Default | Description |
|---|---|---|---|
value | string | - | 탭 고유 값 (필수) |
label | string | - | 표시 텍스트 (미지정 시 value 사용) |
disabled | boolean | false | 개별 비활성화 |
Utility Exports
| Export | Type | Description |
|---|---|---|
tagViewDefaultContextMenuItems | (tab: TagViewItem, allItems: TagViewItem[]) => ContextMenuItem[] | 기본 컨텍스트 메뉴 항목 생성 헬퍼 |
접근성
권장 사항
- ✅
role="tablist"/role="tab"/aria-selected적용 - ✅
aria-disabled로 비활성화 상태 전달 - ✅ Enter / Space 키로 탭 선택
- ✅
focus-visible시 ring 스타일로 포커스 표시 - ✅
aria-labelprop으로 접근성 레이블 지정 가능
관련 컴포넌트
- Tabs: 콘텐츠 영역 전환용 탭 컴포넌트
- ContextMenu: 우클릭 메뉴 (내부적으로 사용)
Last updated on