Tabs
Tabs 컴포넌트는 컨테이너 안에서 여러 항목 중 하나를 선택하는 탭형 토글입니다. 구분선 색 테두리를 두른 네이비 컨테이너 안에서 선택된 탭은 노란(primary) 글자, 미선택 탭은 흰 글자로 표시되며, 지역·기간 필터 같은 단일 선택 UI에 적합합니다. 선택 상태는 기본적으로 컴포넌트가 직접 관리하며, 바깥에서 그 값을 읽거나 바꿔야 할 때만 value / onValueChange 로 제어합니다.
기본 사용법
import { Tabs } from '@youngduck/yd-ui'
function App() {
return (
<Tabs
defaultValue="all"
options={[
{ label: '전체', value: 'all' },
{ label: '국내', value: 'domestic' },
{ label: '해외', value: 'overseas' },
]}
/>
)
}비제어와 제어
탭 선택값은 대부분 그 화면 안에서만 쓰입니다. 그래서 기본은 비제어이고, 처음 선택해둘 탭만 defaultValue 로 주면 됩니다.
<Tabs defaultValue="all" options={options} />defaultValue 를 생략하면 아무 탭도 선택되지 않습니다
선택을 자동으로 첫 탭에 맞추지 않습니다. 첫 탭부터 시작하려면 그 탭의 value 를 defaultValue 로 명시하세요.
선택값을 탭 바깥에서 읽거나 직접 바꿔야 할 때만 value / onValueChange 를 줍니다. 목록을 필터링하거나 URL 쿼리와 맞출 때가 그런 경우입니다.
const [region, setRegion] = useState('all')
return (
<>
<Tabs value={region} onValueChange={setRegion} options={options} />
<ProductList region={region} />
</>
)어느 쪽인지 판단하는 기준
useState 로 만든 값이 <Tabs> 에 돌려주는 것 말고 아무 데도 쓰이지 않는다면 제어가 필요 없는 경우입니다.
onValueChange 는 비제어 모드에서도 호출되므로, 상태를 넘기지 않고 변경 알림만 받을 수도 있습니다.
주요 특징
- 비제어 기본:
defaultValue로 처음 선택할 탭만 지정하면 선택 상태는 컴포넌트가 직접 관리합니다. - 필요할 때만 제어:
value/onValueChange를 주면 선택값을 바깥에서 관리합니다. - options 기반:
{ label, value, disabled? }배열로 탭을 구성합니다. - 선택 강조: 선택된 탭은 연노랑(primary-200) 글자, 미선택 탭은 흰 글자로 표시됩니다.
- 구분선 테두리: 컨테이너에 Table 행 구분선과 같은
--color-border-divider토큰의 테두리가 적용됩니다. - 사이즈 지원: sm / md / lg 세 가지 사이즈 제공 (기본값 md)
- 접근성:
role="radiogroup"/role="radio", 방향키·Home·End 키보드 탐색, 로빙 탭인덱스 적용 - 디자인 토큰: 색상·간격·타이포그래피를 모두 토큰에서 일괄 적용
Variants
variant prop으로 탭 모양을 고릅니다. 두 모양 모두 선택·비제어·키보드 동작은 같습니다.
- segmented (기본): 테두리 컨테이너 안에서 선택합니다. 지역·기간 필터처럼 같은 목록을 걸러 보는 토글에 어울립니다.
- underline: 컨테이너 없이 하단 구분선 위에 노란 표시선으로 선택을 보여줍니다. 페이지 상단에서 화면 영역 자체를 바꾸는 탭에 어울립니다.
<Tabs
variant="underline"
defaultValue="trend"
aria-label="주식 정보"
options={[
{ label: '실시간 차트', value: 'chart' },
{ label: '지금 뜨는 산업', value: 'industry' },
{ label: '외국인·기관 매매 동향', value: 'trend' },
]}
/>underline 은 부모 폭만큼 하단 구분선이 늘어나며, 높이는 48px 로 고정되고 size 는 글자 크기만 바꿉니다.
Sizes
size prop으로 sm / md / lg 를 선택할 수 있습니다.
// Small
<Tabs size="sm" defaultValue="all" options={options} />
// Medium (기본)
<Tabs size="md" defaultValue="all" options={options} />
// Large
<Tabs size="lg" defaultValue="all" options={options} />탭 비활성화
특정 탭만 비활성화하려면 해당 옵션에 disabled: true 를 지정합니다. 비활성화된 탭은 클릭·키보드 탐색에서 자동으로 제외됩니다.
<Tabs
defaultValue="all"
options={[
{ label: '전체', value: 'all' },
{ label: '국내', value: 'domestic' },
{ label: '해외', value: 'overseas', disabled: true },
]}
/>여러 필터 조합
여러 Tabs를 필터로 함께 배치할 수 있습니다. 각 그룹을 구분하기 위해 aria-label 을 지정하는 것을 권장합니다.
const [region, setRegion] = useState('all')
const [period, setPeriod] = useState('day')
<div className="flex flex-wrap items-center gap-4">
<Tabs
value={region}
onValueChange={setRegion}
aria-label="지역 필터"
options={[
{ label: '전체', value: 'all' },
{ label: '국내', value: 'domestic' },
{ label: '해외', value: 'overseas' },
]}
/>
<Tabs
value={period}
onValueChange={setPeriod}
aria-label="기간 필터"
options={[
{ label: '일간', value: 'day' },
{ label: '주간', value: 'week' },
{ label: '월간', value: 'month' },
]}
/>
</div>키보드 접근성
Tabs는 WAI-ARIA radiogroup 패턴을 따릅니다.
| 키 | 동작 |
|---|---|
Tab | 선택된 탭으로 포커스 진입 (로빙 탭인덱스) |
← / ↑ | 이전 탭 선택 (비활성 탭 건너뜀, 순환) |
→ / ↓ | 다음 탭 선택 (비활성 탭 건너뜀, 순환) |
Home | 첫 번째 탭 선택 |
End | 마지막 탭 선택 |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
options | TabOption[] | - | 탭 항목 목록 (필수) |
defaultValue | string | - | 처음 선택해둘 값 (비제어 모드) |
value | string | - | 현재 선택된 값. 주면 제어 모드 |
onValueChange | (value: string) => void | - | 값 변경 시 호출 (두 모드 모두) |
size | 'sm' | 'md' | 'lg' | 'md' | 탭 사이즈 |
variant | 'segmented' | 'underline' | 'segmented' | 탭 모양 (테두리 / 하단 표시선) |
aria-label | string | '탭' | radiogroup 라벨 |
TabOption 타입은 다음과 같습니다.
type TabOption = {
label: string // 화면에 노출되는 라벨
value: string // 선택 값으로 사용되는 고유 값
disabled?: boolean // 개별 탭 비활성화 여부
}Tabs는 표준 HTML div 요소의 속성(onChange 제외)을 함께 지원합니다.
디자인 토큰
Tabs 컴포넌트는 다음 디자인 토큰을 사용합니다.
Spacing Tokens
--tabs-padding: 컨테이너 안쪽 여백 (4px)--tabs-gap: 탭 사이 간격 (2px)--tabs-border-radius: 컨테이너 모서리 반경--tabs-item-border-radius: 개별 탭 모서리 반경 (6px)--tabs-item-padding-x: 탭 좌우 패딩 (16px)--tabs-item-height-sm/-md/-lg: 사이즈별 탭 높이 (28 / 34 / 42px)
Typography Tokens
--tabs-typography-font-size: yds-c1m 폰트 크기--tabs-typography-line-height: yds-c1m 라인 높이--tabs-typography-font-weight: yds-c1m 폰트 굵기--tabs-typography-font-family: Wanted Sans Variable
Color Tokens
--color-tabs-bg: 컨테이너 배경색 (secondary-300)--color-tabs-border: 컨테이너 테두리 색상 (border-divider, Table 구분선과 공유)--color-tabs-item-text: 미선택 탭 텍스트 색상 (white)--color-tabs-item-text-hover: 미선택 탭 hover 텍스트 색상 (primary-50)--color-tabs-item-selected-text: 선택된 탭 텍스트 색상 (primary-200, 연노랑)--color-tabs-focus-ring: 포커스 링 색상 (white)
Underline Variant Tokens
--tabs-underline-gap: 탭 사이 간격 (24px)--tabs-underline-item-height: 탭 높이 (48px)--tabs-underline-item-padding-x: 탭 좌우 패딩 (4px)--tabs-underline-indicator-height: 선택 표시선 두께 (2px)--color-tabs-underline-border: 하단 구분선 색상 (border-divider)--color-tabs-underline-item-text: 미선택 탭 텍스트 색상 (primary-100)--color-tabs-underline-item-text-hover: 미선택 탭 hover 텍스트 색상 (primary-50)--color-tabs-underline-item-selected-text: 선택된 탭 텍스트 색상 (primary-200)--color-tabs-underline-indicator: 선택 표시선 색상 (primary-200)
