본문으로 건너뛰기

ZSSegmented

트랙 안에서 선택 블록(thumb)이 미끄러지는 세그먼트 컨트롤입니다. 값 선택·필터 토글에 사용합니다.

콘텐츠를 전환하는 내비게이션 성격이라면 ZSTab이 더 적합합니다.

ZSSegmentedZSTab
형태트랙 + 슬라이딩 블록하단 밑줄 인디케이터
용도값 선택 · 필터 토글화면 내 콘텐츠 전환
식별자배열 인덱스items 의 value 문자열
앱 예제 Playgroundv0.19.4
소스 보기새 창에서 열기
Interactive exampleZSSegmented 로컬 웹 예제

예제를 선택하면 현재 저장소 소스로 만든 Expo Web 화면을 불러옵니다.

웹 미지원 또는 플랫폼 종속 기능은 실제 iOS·Android 앱에서 확인하세요.

기본 사용법​

import { ZSSegmented } from '@0610studio/zs-ui';
import { useState } from 'react';

function MyControl() {
  const [index, setIndex] = useState(0);

  return (
    <ZSSegmented
      options={['일간', '주간', '월간']}
      selectedIndex={index}
      onChange={setIndex}
    />
  );
}

Props​

PropTypeDefaultDescription
optionsstring[]Required세그먼트 라벨 목록 (2개 이상)
selectedIndexnumberundefined선택 인덱스를 외부에서 제어할 때 사용 (미지정 시 내부 상태로 동작)
initialIndexnumber0비제어 모드의 초기 선택 인덱스
onChange(index: number) => voidundefined세그먼트 선택 시 호출. 이미 선택된 세그먼트를 눌러도 호출되지 않습니다
fullWidthbooleantruetrue: 부모 폭을 가득 채워 균등 분할 · false: 가장 긴 라벨 폭에 맞춤
containerHeightnumber40컨트롤 높이(px). 곡률은 높이의 절반으로 자동 계산됩니다
textSize'1' ~ '6''2'라벨 typo 크기
trackColorstring테마 background.layer2트랙 배경색
thumbColorstring테마 background.base선택 블록 색상
disabledbooleanfalse비활성화
styleStyleProp<ViewStyle>undefined컨테이너 추가 스타일
...propsViewProps-React Native View의 모든 기본 속성

특징​

  • thumb 슬라이딩: 선택 블록이 250ms ease-out 으로 이동합니다
  • thumb 그림자: boxShadow 로 렌더해 iOS·Android 가 동일하며, 다크 모드에서는 밝은 그림자로 블록을 구분합니다
  • 라벨 폭 자동 측정: fullWidth={false} 일 때 활성(굵은) typo 기준으로 폭을 측정해, 선택 전환 시 글자가 넘치지 않습니다
  • 말줄임 처리: 폭을 넘는 라벨은 한 줄 말줄임(…)으로 표시됩니다
  • 접근성: 컨테이너에 tablist, 각 세그먼트에 tab 역할과 accessibilityState.selected 를 부여합니다

레이아웃​

fullWidth (기본값)​

부모 폭을 세그먼트 개수로 균등 분할합니다.

<ZSSegmented options={['일간', '주간', '월간', '연간']} onChange={setIndex} />

fullWidth={false}​

가장 긴 라벨과 글자 크기에 맞춰 전체 폭이 결정됩니다. 화면 일부에만 놓을 때 사용합니다.

<ZSSegmented fullWidth={false} options={['ON', 'OFF']} />
<ZSSegmented fullWidth={false} options={['오늘', '이번 주', '최근 30일']} />

예제​

콘텐츠 전환​

const TABS = ['홈', '검색', '알림'];
const [index, setIndex] = useState(0);

<ZSSegmented options={TABS} onChange={setIndex} />
{index === 0 && <HomeView />}
{index === 1 && <SearchView />}
{index === 2 && <NotificationView />}

크기 조절​

textSize 와 containerHeight 를 함께 맞추면 비율이 자연스럽습니다.

<ZSSegmented options={['왼쪽', '오른쪽']} textSize="1" containerHeight={48} />
<ZSSegmented options={['왼쪽', '오른쪽']} textSize="3" containerHeight={40} />
<ZSSegmented options={['왼쪽', '오른쪽']} textSize="6" containerHeight={32} />

커스텀 색상​

<ZSSegmented
  options={['라이트', '다크']}
  trackColor="#EEF2F6"
  thumbColor="#FFFFFF"
/>

비제어 모드​

selectedIndex 를 넘기지 않으면 내부 상태로 동작합니다.

<ZSSegmented
  options={['최신순', '인기순']}
  initialIndex={1}
  onChange={(index) => refetch(index)}
/>