Segmented Control

여러 옵션 중 하나를 선택해 관련 콘텐츠를 즉시 필터링하거나 전환할 때 쓰는 컴포넌트예요.

설치

pnpm dlx shadcn@latest add https://rebar.conmarket-landing.workers.dev/r/segmented-control.json

pnpm dlx shadcn@latest add https://rebar.conmarket-landing.workers.dev/r/segmented-control.json

radix-ui 를 설치하고 아래 코드를 components/ui/segmented-control.tsx 에 복사해요.

components/ui/segmented-control.tsx

'use client';/** * @title Segmented Control * @description 여러 옵션 중 하나를 선택해 관련 콘텐츠를 즉시 필터링하거나 전환할 때 쓰는 컴포넌트예요. */import * as React from 'react';import { RadioGroup as RadioGroupPrimitive } from 'radix-ui';import { cn } from '@/lib/utils';// SEED Rootage spec: segmented-control.yaml, segmented-control-item.yaml, segmented-control-indicator.yaml/** * 선택된 아이템의 순서와 전체 개수를 CSS 변수(--segment-index, --segment-count)로 루트에 기록해요. * 제어/비제어 모두에서 동작하도록 DOM 의 data-state 변화를 관찰해요. */function useSegmentIndicator(rootRef: React.RefObject<HTMLDivElement | null>) {  React.useLayoutEffect(() => {    const root = rootRef.current;    if (!root) return;    let frame = 0;    const update = () => {      const items = Array.from(        root.querySelectorAll<HTMLElement>(':scope > [data-slot="segmented-control-item"]'),      );      const index = items.findIndex((item) => item.dataset.state === 'checked');      root.style.setProperty('--segment-count', String(Math.max(items.length, 1)));      root.style.setProperty('--segment-index', String(Math.max(index, 0)));      if (index < 0) {        root.setAttribute('data-indicator', 'none');        return;      }      const state = root.getAttribute('data-indicator');      if (state !== 'pending' && state !== 'ready') {        root.setAttribute('data-indicator', 'pending');        // 첫 위치를 잡은 다음 프레임부터 이동 애니메이션을 켜요.        cancelAnimationFrame(frame);        frame = requestAnimationFrame(() => root.setAttribute('data-indicator', 'ready'));      }    };    update();    const observer = new MutationObserver(update);    observer.observe(root, { subtree: true, childList: true, attributes: true, attributeFilter: ['data-state'] });    return () => {      observer.disconnect();      cancelAnimationFrame(frame);    };  }, [rootRef]);}export interface SegmentedControlProps  extends Omit<React.ComponentProps<typeof RadioGroupPrimitive.Root>, 'orientation' | 'dir'> {}function SegmentedControl({ className, children, ref, ...props }: SegmentedControlProps) {  const rootRef = React.useRef<HTMLDivElement>(null);  useSegmentIndicator(rootRef);  const mergedRef = React.useCallback(    (node: HTMLDivElement | null) => {      rootRef.current = node;      if (typeof ref === 'function') ref(node);      else if (ref) ref.current = node;    },    [ref],  );  return (    <RadioGroupPrimitive.Root      ref={mergedRef}      data-slot="segmented-control"      // 하이드레이션 전에는 선택된 아이템이 직접 배경을 그려요 (인디케이터는 측정 후 표시).      data-indicator="ssr"      orientation="horizontal"      className={cn(        'group/segmented-control relative isolate box-border inline-grid max-w-full auto-cols-fr auto-rows-fr grid-flow-col items-center',        'rounded-full bg-bg-neutral-weak-alpha p-x1',        className,      )}      {...props}    >      {children}      <span        aria-hidden        data-slot="segmented-control-indicator"        className={cn(          'pointer-events-none absolute inset-y-x1 left-x1 -z-1 hidden rounded-full will-change-transform',          'w-[calc((100%-var(--rb-dimension-x1)*2)/var(--segment-count,1))]',          '[transform:translateX(calc(var(--segment-index,0)*100%))]',          'bg-palette-gray-00 shadow-[inset_0_0_0_1px_var(--rb-color-stroke-neutral-muted)]',          'group-data-[indicator=pending]/segmented-control:block group-data-[indicator=ready]/segmented-control:block',          'group-data-[indicator=ready]/segmented-control:transition-transform group-data-[indicator=ready]/segmented-control:duration-(--rb-duration-d4) group-data-[indicator=ready]/segmented-control:ease-easing',          'motion-reduce:transition-none',        )}      />    </RadioGroupPrimitive.Root>  );}export interface SegmentedControlItemProps extends React.ComponentProps<typeof RadioGroupPrimitive.Item> {  /** 라벨 오른쪽 위에 새 소식을 알리는 Notification Badge(점)를 보여줘요. */  notification?: boolean;}function SegmentedControlItem({ className, children, notification = false, ...props }: SegmentedControlItemProps) {  return (    <RadioGroupPrimitive.Item      data-slot="segmented-control-item"      className={cn(        'group/segmented-control-item box-border flex h-full min-h-[34px] min-w-[86px] cursor-pointer select-none items-center justify-center text-center [overflow-wrap:break-word]',        'gap-x1_5 rounded-full px-x6 py-x1_5 text-t5 font-bold text-fg-neutral-subtle',        'transition-[background-color,color,box-shadow,outline-color] duration-(--rb-duration-color-transition) ease-easing',        'outline-2 outline-offset-2 outline-transparent focus-visible:outline-stroke-focus-ring',        'data-[state=checked]:text-fg-neutral',        'group-data-[indicator=ssr]/segmented-control:data-[state=checked]:bg-palette-gray-00 group-data-[indicator=ssr]/segmented-control:data-[state=checked]:shadow-[inset_0_0_0_1px_var(--rb-color-stroke-neutral-muted)]',        // pressed        'enabled:active:bg-bg-neutral-weak-pressed enabled:active:shadow-[inset_0_0_0_1px_var(--rb-color-stroke-neutral-muted)]',        'enabled:data-[state=checked]:active:bg-palette-gray-100',        // disabled        'disabled:cursor-not-allowed disabled:text-fg-disabled',        'disabled:data-[state=checked]:bg-bg-disabled disabled:data-[state=checked]:shadow-[inset_0_0_0_1px_var(--rb-color-stroke-neutral-muted)]',        className,      )}      {...props}    >      {/* SEED scaleScope: content — 배경은 그대로 두고 콘텐츠만 줄어들어요. */}      <span        data-slot="segmented-control-item-label"        className={cn(          'inline-flex min-w-0 items-center justify-center gap-[inherit]',          'transition-[scale] duration-(--rb-duration-pressed-scale) ease-pressed-scale',          'group-enabled/segmented-control-item:group-active/segmented-control-item:scale-[0.95] motion-reduce:scale-100',        )}      >        {notification ? (          <span className="relative">            {children}            <span              aria-hidden              data-slot="segmented-control-notification"              className="absolute top-0 -right-[8px] size-[6px] rounded-full bg-bg-brand-solid"            />          </span>        ) : (          children        )}      </span>    </RadioGroupPrimitive.Item>  );}export { SegmentedControl, SegmentedControlItem };

Anatomy

Segmented Control은 전체를 감싸는 Container 안에 여러 개의 Segment가 자리 잡고 있고, 각 Segment는 텍스트 Label을 포함해요. 선택된 Segment 뒤에는 Indicator가 깔리고, 선택이 바뀌면 Indicator가 부드럽게 미끄러지듯 이동해요.

새로운 Segment가 생기거나 해당 Segment에 새로운 내용이 추가된 경우 Notification Badge를 선택적으로 표시할 수 있어요.

요소	`data-slot`	설명
Container	`segmented-control`	Segment를 감싸는 둥근 배경이에요.
Segment	`segmented-control-item`	하나의 선택지예요. 키보드 방향키로 이동하며 선택해요.
Indicator	`segmented-control-indicator`	선택된 Segment 뒤에서 움직이는 흰색 배경이에요.
Notification Badge (Optional)	`segmented-control-notification`	새 소식이 있음을 알리는 점이에요.

Properties

Number of Controls

Segment는 2~4개로 구성할 수 있어요. 모든 Segment는 가장 넓은 Segment에 맞춰 같은 너비를 가져요.

State

Selected/Unselected 상태로 선택 여부를 표시하고, Enabled, Pressed, Disabled 같은 상호작용 상태를 함께 가져요. 눌렀을 때는 배경은 그대로 두고 라벨만 살짝 작아져요.

Notification

Segment에 새로운 내용이 있다면 notification 으로 Notification Badge를 표시해요. 사용자가 해당 Segment를 확인하면 Badge를 숨겨요.

Long Label

라벨이 길면 줄바꿈되고, 모든 Segment가 가장 높은 Segment에 맞춰 같은 높이를 가져요.

Fixed Width

style 이나 className 으로 너비를 직접 지정할 수 있어요. 지정하지 않으면 콘텐츠에 맞춰져요.

Listening to Value Changes

onValueChange 로 선택 값이 바뀌는 것을 감지할 수 있어요. value 와 함께 쓰면 제어 컴포넌트로 동작해요.

현재 정렬: 가까운 순

Guidelines

짧고 간단하게 작성하기

라벨은 짧고 간결하게 유지해요. 라벨이 Segment에 비해 너무 길다면 다른 컴포넌트를 쓰는 것을 고려해요.

인기순추천순

Do· 짧은 라벨

Segment를 표현하는 라벨은 짧고 간결하게 써요.

가장 인기 있는 리뷰추천이 많은 리뷰

Don't· 긴 라벨

라벨이 길면 한눈에 비교하기 어려워요.

4개 이하로 사용하기

선택지가 너무 많아지면 사용자가 인식하기 어렵고, 모바일 환경에서는 터치 영역이 좁아져 사용성이 떨어져요. 옵션을 5개 이상 쓰지 않아요. 더 많은 옵션이 필요하면 Radio Group, Checkbox Group 같은 다른 컴포넌트를 쓰는 것이 좋아요.

한 화면에 한 개만 사용하기

Segmented Control을 한 화면에 반복해서 쓰는 것은 권장하지 않아요. 같은 형태의 컨트롤이 여러 개 있으면 화면의 시각적 계층이 모호해져, 사용자는 어떤 것을 먼저 조작해야 할지, 각 컨트롤이 어느 영역에 영향을 주는지 파악하기 어려워요.

보기 전환하기

Segmented Control은 특정 콘텐츠 영역에 직접 영향을 주는 상호작용에 써요. 같은 데이터를 다른 방식으로 보여줄 때 쓰며, '지도로 보기'와 '목록으로 보기' 전환이 대표적이에요. 사용자는 화면 내용이 즉시 바뀌기를 기대해요.

필터링으로 활용하기

연관된 콘텐츠 그룹을 필터링할 때 Segmented Control을 쓰면 사용자가 보기 안의 콘텐츠 범위를 좁히거나 넓히며 원하는 콘텐츠를 쉽게 찾을 수 있어요.

보기 안에서 콘텐츠 탐색하기

같은 콘텐츠를 여러 관점이나 기준으로 보여주고 싶을 때, Segmented Control로 각 기준을 손쉽게 전환하게 만들 수 있어요.