Skip to Content

TagView

화면 상단의 열린 탭 목록을 태그 형태로 보여주고, 클릭·닫기·우클릭 메뉴를 지원하는 탭 네비게이션 컴포넌트


개요

TagView는 화면(메뉴) 단위의 탭 관리에 특화된 컴포넌트입니다. 기존 Tabs 컴포넌트가 콘텐츠 영역 전환에 초점을 맞추는 반면, TagView는 열린 화면 목록을 관리하는 데 적합합니다.

주요 특징

  • 탭 선택/해제: 단일 선택, 재클릭 시 해제
  • Closable: X 버튼으로 탭 닫기 + onClose 콜백
  • 닫기 가드: onBeforeClose로 닫기 전 확인 (비동기 지원)
  • ContextMenu: 우클릭 시 닫기/다른 탭 닫기/모두 닫기 + 커스텀 메뉴 확장
  • Controlled/Uncontrolled: value 또는 defaultValue

기본 사용

items 배열로 탭 목록을 정의하고, value/onValueChange로 선택 상태를 관리합니다.

선택된 탭: dashboard

닫기 기능 (Closable)

closable prop을 활성화하면 각 탭에 X 버튼이 표시됩니다. onClose에서 탭을 제거합니다.

열린 탭: 4

닫기 가드 (onBeforeClose)

onBeforeClose를 사용하면 닫기 직전에 확인을 물어볼 수 있습니다. false를 반환하면 닫기가 취소됩니다. Promise도 지원합니다.

"대시보드" 탭은 닫기 전에 확인을 물어봅니다.

커스텀 컨텍스트 메뉴

contextMenuItems에 팩토리 함수를 전달하면 기본 메뉴에 커스텀 항목을 추가할 수 있습니다. tagViewDefaultContextMenuItems를 import하여 기본 메뉴를 포함시킵니다.

마지막 액션: (우클릭해 보세요)

비활성화

disabled prop으로 전체 비활성화하거나, 개별 항목의 disabled로 특정 탭만 비활성화합니다.


API Reference

Props

PropTypeDefaultDescription
itemsTagViewItem[][]탭 항목 목록
valuestring-선택된 탭 값 (Controlled)
defaultValuestring-초기 선택 탭 값 (Uncontrolled)
disabledbooleanfalse전체 비활성화
closablebooleanfalse닫기(X) 버튼 표시 여부
visiblebooleantrue표시 여부
contextMenuItemsContextMenuItem[] | TagViewContextMenuFactory-커스텀 컨텍스트 메뉴 (배열: 기본 대체, 팩토리: 자유 구성)
classNamestring-추가 CSS 클래스
aria-labelstring-접근성 레이블

Events

EventTypeDescription
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

PropertyTypeDefaultDescription
valuestring-탭 고유 값 (필수)
labelstring-표시 텍스트 (미지정 시 value 사용)
disabledbooleanfalse개별 비활성화

Utility Exports

ExportTypeDescription
tagViewDefaultContextMenuItems(tab: TagViewItem, allItems: TagViewItem[]) => ContextMenuItem[]기본 컨텍스트 메뉴 항목 생성 헬퍼

접근성

권장 사항

  • role="tablist" / role="tab" / aria-selected 적용
  • aria-disabled 로 비활성화 상태 전달
  • ✅ Enter / Space 키로 탭 선택
  • focus-visible 시 ring 스타일로 포커스 표시
  • aria-label prop으로 접근성 레이블 지정 가능

관련 컴포넌트

  • Tabs: 콘텐츠 영역 전환용 탭 컴포넌트
  • ContextMenu: 우클릭 메뉴 (내부적으로 사용)
Last updated on