메인 컨텐츠로 이동
버전: Canary 🚧

탭

도큐사우루스는 MDX 기반으로 <Tabs> 컴포넌트를 마크다운에서 사용할 수 있게 지원합니다.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="apple" label="Apple" default>
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange">
    This is an orange 🍊
  </TabItem>
  <TabItem value="banana" label="Banana">
    This is a banana 🍌
  </TabItem>
</Tabs>
http://localhost:3000
This is an apple 🍎

Tabs에 values와 defaultValue 속성을 설정할 수 있습니다.

<Tabs
  defaultValue="apple"
  values={[
    {label: 'Apple', value: 'apple'},
    {label: 'Orange', value: 'orange'},
    {label: 'Banana', value: 'banana'},
  ]}>
  <TabItem value="apple">This is an apple 🍎</TabItem>
  <TabItem value="orange">This is an orange 🍊</TabItem>
  <TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs>
http://localhost:3000
This is an apple 🍎
Tabs 속성은 TabItem 속성보다 우선합니다.
<Tabs
  defaultValue="apple"
  values={[
    {label: 'Apple 1', value: 'apple'},
    {label: 'Orange 1', value: 'orange'},
    {label: 'Banana 1', value: 'banana'},
  ]}>
  <TabItem value="apple" label="Apple 2">
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange 2">
    This is an orange 🍊
  </TabItem>
  <TabItem value="banana" label="Banana 2" default>
    This is a banana 🍌
  </TabItem>
</Tabs>
http://localhost:3000
This is an apple 🍎
팁

기본적으로 모든 탭은 빌드 단계에서 빠르게 렌더링되며 검색 엔진은 숨겨진 탭까지 색인 처리합니다.

<Tabs lazy /> 설정 시 기본 탭만 렌더링하도록 설정할 수 있습니다.

기본 탭 표시하기​

기본적으로 표시되는 첫 번째 탭의 동작을 직접 설정할 수 있습니다. tab 아이템 중 하나를 default로 설정해 기본 탭을 지정할 수 있습니다. Tabs 컴포넌트의 defaultValue 속성을 원하는 라벨값으로 설정할 수도 있습니다. 예를 들어 위의 예제에서는 value="apple" 탭에 default를 설정하거나 defaultValue="apple"을 설정하면 "Apple" 탭을 기본적으로 표시되는 탭으로 지정할 수 있습니다.

Tabs에 defaultValue 값을 설정했는데 존재하지 않은 값을 참조하는 경우 도큐사우루스에서는 오류로 처리합니다. 기본적으로 탭이 표시되지 않도록 하려면 defaultValue={null}로 설정하세요.

탭 선택 항목 동기화​

같은 종류의 탭이라면 선택한 항목을 서로 동기화하기를 원할 수 있습니다. 예를 들어 윈도와 macOS 사용자에게 다른 사용법을 가이드하는 경우 한 번의 클릭으로 탭에서 선택한 운영체제를 변경하고 싶을 수 있습니다. 관련된 탭을 같은 groupId 속성으로 설정하면 원하는 기능을 구현할 수 있습니다. 이렇게 하면 선택한 값이 localStorage에 저장되고 같은 groupId 속성값으로 설정한 <Tab> 인스턴스는 값이 변경될 때마다 자동으로 업데이트됩니다. group ID는 전역 네임스페이스입니다.

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Use Ctrl + C to copy.</TabItem>
  <TabItem value="mac" label="macOS">Use Command + C to copy.</TabItem>
</Tabs>

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Use Ctrl + V to paste.</TabItem>
  <TabItem value="mac" label="macOS">Use Command + V to paste.</TabItem>
</Tabs>
http://localhost:3000
Use Ctrl + C to copy.
Use Ctrl + V to paste.

같은 groupId 속성으로 설정한 모든 탭 그룹에서 사용할 수 있는 값이 똑같을 필요는 없습니다. 같은 groupId으로 설정한 다른 탭 그룹에는 없는 값을 선택했을 때는 변경된 값이 탭에 반영되지 않을 뿐입니다. 다음 예제가 그런 상황입니다. 탭에서 리눅스 항목을 선택해도 위에 있는 탭은 변경되지 않는 것을 확인할 수 있습니다.

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">
    I am Windows.
  </TabItem>
  <TabItem value="mac" label="macOS">
    I am macOS.
  </TabItem>
  <TabItem value="linux" label="Linux">
    I am Linux.
  </TabItem>
</Tabs>
http://localhost:3000
I am Windows.

group ID 속성값이 다른 탭은 서로 영향을 미치지 않습니다.

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Windows in windows.</TabItem>
  <TabItem value="mac" label="macOS">macOS is macOS.</TabItem>
</Tabs>

<Tabs groupId="non-mac-operating-systems">
  <TabItem value="win" label="Windows">Windows is windows.</TabItem>
  <TabItem value="unix" label="Unix">Unix is unix.</TabItem>
</Tabs>
http://localhost:3000
Windows in windows.
Windows is windows.

탭에 사용자 지정 스타일 적용하기​

특정 탭은 사용자가 원하는 스타일로 변경할 수 있습니다. Tabs 컴포넌트에 className 속성을 추가하고 원하는 CSS 클래스를 지정합니다.

<Tabs className="unique-tabs">
  <TabItem value="Apple">This is an apple 🍎</TabItem>
  <TabItem value="Orange">This is an orange 🍊</TabItem>
  <TabItem value="Banana">This is a banana 🍌</TabItem>
</Tabs>
http://localhost:3000
This is an apple 🍎

탭 제목 사용자 지정하기​

attributes 필드를 사용해 각 탭 제목을 개별적으로 사용자 지정할 수 있습니다. 추가 속성은 label을 선언하는 것과 같은 방법으로 Tabs의 values 속성이나 각 TabItem의 속성을 통해 제목에 전달할 수 있습니다.

some-doc.mdx
import styles from './styles.module.css';

<Tabs>
  <TabItem value="apple" label="Apple" attributes={{className: styles.red}}>
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange" attributes={{className: styles.orange}}>
    This is an orange 🍊
  </TabItem>
  <TabItem value="banana" label="Banana" attributes={{className: styles.yellow}}>
    This is a banana 🍌
  </TabItem>
</Tabs>
styles.module.css
.red {
  color: red;
}
.red[aria-selected='true'] {
  border-bottom-color: red;
}

.orange {
  color: orange;
}
.orange[aria-selected='true'] {
  border-bottom-color: orange;
}

.yellow {
  color: yellow;
}
.yellow[aria-selected='true'] {
  border-bottom-color: yellow;
}
http://localhost:3000
This is an apple 🍎
팁

className은 다른 기본 클래스 이름과 합쳐집니다. CSS 속성 선택자와 매칭되는 사용자 정의 data-value field ({'data-value': 'apple'})를 사용할 수 있습니다.

styles.module.css
li[role='tab'][data-value='apple'] {
  color: red;
}

쿼리 문자열​

선택한 탭을 URL 검색 파라미터로 유지할 수 있습니다. 이 기능을 사용하면 탭이 미리 선택된 페이지로 연결되는 링크를 공유할 수 있습니다. 즉, 안드로이드 앱에서는 미리 선택된 안드로이드 탭이 있는 문서로 연결할 수 있습니다. 이 기능은 앵커 링크를 제공하지 않으므로 브라우저에서 탭으로 스크롤되지 않습니다.

queryString 속성을 사용해 기능을 활성화하고 사용할 검색 파라미터 이름을 정의하세요.

<Tabs queryString="current-os">
  <TabItem value="android" label="Android">
    Android
  </TabItem>
  <TabItem value="ios" label="iOS">
    iOS
  </TabItem>
</Tabs>
http://localhost:3000
Android

탭을 클릭하면 다음과 같이 URL 끝에 검색 파라미터가 추가됩니다. ?current-os=android or ?current-os=ios.

팁

queryString은 groupId와 같이 사용할 수 있습니다.

편의를 위해 queryString 속성값이 true이면 groupId 속성값은 폴백으로 사용됩니다.

<Tabs groupId="current-os" queryString>
  <TabItem value="android" label="Android">
    Android
  </TabItem>
  <TabItem value="ios" label="iOS">
    iOS
  </TabItem>
</Tabs>
http://localhost:3000
Android

페이지가 로드되면 탭 쿼리 문자열 선택이 groupId 선택(localStorage 사용)보다 우선 순위로 복원됩니다.