Segment Control

옵션 하나를 골라 같은 화면에서 바로 필터링하거나 뷰를 전환해요.

Anatomy

01
Container
Filled/Outlined 는 패딩 3px·radius-md 상자, Pill 은 배경 없이 항목만
02
Segment Item
선택 단위. 선택되면 배경·글자색이 바뀌고 radius-sm(8px)
03
Count Badge
Pill 전용. 결과 수를 표시하는 radius-full 배지

Properties

Variant

Pill 은 필터링(Count badge 로 결과 수 표시), Filled 는 리스트/그리드 같은 뷰 전환, Outlined 는 배경이 이미 채워진 영역의 2차 컨트롤이에요.

Layout

base 는 fill 로 두고 전체 width 를 조절해요. Fill 은 옵션 5개 이하일 때만, 많아지면 Hug 예요.

Size

같은 화면에선 사이즈를 통일해요. SM 은 좁은 패널·툴바에 써요.

State

Enabled · Selected · Disabled. Segment Control 의 Disabled 는 투명도 35% 예요.

Case

base 는 fill 로 두고 전체 width 를 조절해요. 높이도 같아요.

Guidelines

언제 써요

고르는 순간 같은 화면이 바뀌어야 해요. 페이지 이동이 아니라 결과를 거르거나 표시 방식을 바꾸는 용도이고, 옵션 2~5개일 때 가장 좋아요.

✓ DO

카테고리·상태 필터링
리스트/그리드/캘린더 뷰 전환
옵션 2~5개
선택 결과가 같은 화면에 바로 반영될 때

✗ DON'T

페이지·섹션 이동(네비게이션 몫)
선택마다 URL 이 바뀌는 라우팅
옵션 6개 이상
탭마다 전혀 다른 콘텐츠로 이동

Variant 선택

Count badge 가 필요하면 Pill 이에요. Fill 레이아웃은 옵션 5개 이하일 때만, 많아지면 Hug 예요.

단일 선택 원칙

항상 하나만 선택돼요. 복수 선택은 Checkbox 나 Filter Chip 이에요.

Specification

Container

Segment Control 컨테이너 스펙
속성	Filled / Outlined	Pill
height (MD)	`44px`	`— (auto)`
height (SM)	`36px`	`— (auto)`
border-radius	`radius-md (10px)`	`radius-full (999px)`
padding (container)	`3px`	`0`
gap	`2px`	`4px`
background	`--color-bg-layer1`	`transparent`

Item

Segment Item 상태별 스펙
속성	State	Filled	Outlined
background	Selected	`--color-accent-normal`	`--color-bg-white`
background	Enabled	`transparent`	`transparent`
color	Selected	`--color-label-inverse`	`--color-label-normal`
color	Enabled	`--color-label-subtle`	`--color-label-subtle`
box-shadow	Selected	`none`	`shadow-sm`
border-radius	—	`radius-sm (8px)`	`radius-sm (8px)`

Count Badge

Count badge 는 Pill 전용이에요.

Count badge 스펙 (Pill 전용)
속성	Selected	Enabled
background	`rgba(255,255,255,0.28)`	`--color-bg-layer2`
color	`--color-label-inverse`	`--color-label-subtle`
font-size	`11px`	`11px`
padding	`2px 8px`	`2px 8px`
border-radius	`radius-full (999px)`	`radius-full (999px)`

⚠️ 위 표의 --color-label-subtle → --color-label-alternative 중 앞쪽 이름은 tokens.css 에 실존하지 않아요(Figma 원본 표기 오류). 구현 시 교정값을 써요.

설치

npm i @polarisoffice/pds-react

Variant

Pill(필터링) · Filled(뷰 전환) · Outlined(2차 컨트롤).

import { SegmentControl } from '@polarisoffice/pds-react';

const items = [
  { value: 'all', label: '전체' },
  { value: 'new', label: '최신' },
  { value: 'hot', label: '인기' },
];

<SegmentControl variant="pill" items={items} defaultValue="all" />
<SegmentControl variant="filled" items={items} defaultValue="all" />
<SegmentControl variant="outlined" items={items} defaultValue="all" />

Count Badge

Count badge 는 Pill 전용이에요. Filled/Outlined 에는 표시하지 않아요.

import { SegmentControl } from '@polarisoffice/pds-react';

<SegmentControl
  variant="pill"
  items={[
    { value: 'event', label: '이벤트', count: 3 },
    { value: 'end', label: '종료', count: 4 },
  ]}
  defaultValue="event"
/>

Layout · Size

Fill 은 옵션 5개 이하일 때만. 같은 화면 내 사이즈는 통일해요.

import { SegmentControl } from '@polarisoffice/pds-react';

<SegmentControl layout="fill" size="md" items={items} defaultValue="all" />
<SegmentControl layout="hug" size="sm" items={items} defaultValue="all" />

Controlled

항상 하나만 선택돼요. 복수 선택은 Checkbox 나 Filter Chip 이에요.

import { SegmentControl } from '@polarisoffice/pds-react';
import { useState } from 'react';

const [view, setView] = useState('all');

<SegmentControl items={items} value={view} onChange={setView} />