Skip to Content
ComponentsIcignalTabNavigation

TabNavigation

닫기 버튼이 포함된 pill 스타일 탭 네비게이션 컴포넌트

개요

TabNavigation은 ToggleGroup을 기반으로 한 단일 선택 탭 컴포넌트입니다. pill 형태의 둥근 캡슐 버튼으로 렌더링되며, 각 탭에 닫기(X) 버튼을 제공할 수 있습니다.

주요 특징

  • ✅ 단일 선택: 항상 하나의 탭만 선택 가능
  • ✅ 닫기 버튼: closable prop으로 X 버튼 표시/숨김
  • ✅ 닫기 이벤트: onClose 콜백으로 탭 닫기 처리
  • ✅ FormItem 통합: 레이블, 설명, 에러 메시지 지원
  • ✅ 접근성: role=“group”, 키보드 탐색 지원

기본 사용

대시보드
사용자 관리
설정

Variants

닫기 버튼 유무

탭 1
탭 2
탭 3
탭 1
탭 2
탭 3

Variant 설명

Variant설명사용 사례
기본닫기 버튼 없는 탭고정 탭, 메뉴 전환
closable닫기 버튼이 있는 탭열린 페이지 관리, 동적 탭

States

탭 A
탭 B
탭 A
탭 B
탭 A
탭 B
탭 A
탭 B

사용 예시

예시 1: 열린 페이지 관리

브라우저 탭처럼 열린 페이지를 관리합니다. X 버튼으로 탭을 닫을 수 있습니다.

홈
대시보드
사용자 관리
상품 관리
주문 관리

예시 2: 고정 메뉴 탭

닫기 버튼 없이 고정된 메뉴 탭으로 사용합니다.

개요
분석
리포트

예시 3: 레이블과 함께 사용

FormItem의 레이블, 설명과 함께 사용합니다.

페이지 1
페이지 2
페이지 3

탭을 선택하거나 X 버튼으로 닫을 수 있습니다

API Reference

Props

PropTypeDefaultDescription
itemsToggleGroupItem[]-탭 항목 배열 (필수)
valuestring[]-선택된 값 (제어 모드)
defaultValuestring[][]기본 선택 값
onValueChange(value: string[]) => void-탭 선택 변경 핸들러
closablebooleanfalse닫기(X) 버튼 표시 여부
onClose(value: string) => void-탭 닫기 핸들러
itemOrientation"horizontal" | "vertical""horizontal"탭 배치 방향
disabledbooleanfalse비활성화 여부
labelstring-필드 레이블
labelWidthstring | number-레이블 너비
requiredbooleanfalse필수 여부
orientation"horizontal" | "vertical""horizontal"레이블-필드 배치 방향
descriptionstring-설명 텍스트
errorstring-에러 메시지
classNamestring-추가 CSS 클래스

ToggleGroupItem

PropTypeDescription
valuestring항목 고유 값 (필수)
labelstring표시할 텍스트
disabledboolean개별 항목 비활성화

기본 사용법

import { TabNavigation } from "@vortex/ui-icignal"
 
// 기본 탭
<TabNavigation
  items={[
    { value: "tab1", label: "탭 1" },
    { value: "tab2", label: "탭 2" },
  ]}
  defaultValue={["tab1"]}
/>
 
// 닫기 버튼 포함
<TabNavigation
  items={tabs}
  value={selected}
  onValueChange={setSelected}
  closable
  onClose={(value) => {
    setTabs(tabs.filter((t) => t.value !== value))
  }}
/>

접근성

ARIA 속성

<TabNavigation
  label="열린 페이지"
  items={[
    { value: "home", label: "홈" },
    { value: "settings", label: "설정" },
  ]}
  closable
/>

권장 사항

  • ✅ label을 제공하여 탭 그룹의 목적 전달
  • ✅ 키보드: Tab으로 이동, Space/Enter로 선택, X 버튼도 키보드 접근 가능
  • ✅ role="group" 자동 설정
  • ❌ 레이블 없이 단독 사용 지양

관련 컴포넌트

Last updated on
SwitchTabs