Bottom navigation

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

• 휴대폰 앱의 주요 목적지 3~5개를 엄지가 닿는 화면 아래쪽에 두세요. 각 Item은 아이콘 아래 짧은 라벨이 붙은 링크이고, current로 지금 있는 페이지를 표시합니다.
• 기본으로 AppShell이 사이드바를 숨기는 760px 이하에서만 보입니다. 그래서 넓은 화면에서는 같은 목적지가 사이드바에 있습니다. 휴대폰 전용 앱이면 visible="always"를 설정하세요.
• 뷰포트 아래쪽에 고정되고 홈 인디케이터 아래 안전 영역만큼 여백을 둡니다. 내비게이션이 보이는 동안 토스트는 그 위로 올라가고, AppShell은 내비게이션이 시작하는 곳에서 끝나서 마지막 줄이 가려지지 않습니다. 그 밖의 스크롤 콘텐츠에는 var(--surf-size-bottom-navigation)과 env(safe-area-inset-bottom)을 더한 만큼 아래 여백을 주세요. 직접 만든 프레임 안에 두려면 position="static"을 설정하세요.
• 배지는 개수를 99+까지 보여 주고, true를 주면 점으로 보여 줍니다. badgeLabel은 스크린 리더에 배지의 뜻을 읽어 줍니다(예: "읽지 않음 3개"). 점 배지에는 꼭 필요합니다.

• 목적지를 다섯 개보다 많이, 또는 세 개보다 적게 넣지 마세요. 나머지는 사이드바나 Sheet 메뉴에 두세요.
• 만들기, 공유 같은 작업을 넣지 마세요. 목적지만 담습니다. 작업은 페이지나 Toolbar에 두세요.
• 라벨을 빼고 아이콘만 남기지 마세요. 좁은 화면에서 잘리므로 라벨은 짧은 한 단어로 쓰세요.
• 한 화면 안에서 패널을 전환하는 데 쓰지 마세요. 그때는 Tabs를 쓰세요.

크기: SizeProvider size="small" 포털까지 포함해 구성 전체의 크기를 바꿉니다. 기본 크기는 Default입니다. 크기 안내 및 비교

구성

Root(nav, aria-label) → ul → Item: li → a(aria-current) → icon pill(+ badge) + label + spoken badge

키보드와 접근성

• 각 목적지는 네이티브 링크입니다. Tab으로 이동하고 Enter로 따라갑니다.
• nav 랜드마크의 이름은 aria-label에서 오고, 현재 목적지는 현재 페이지로 읽힙니다.
• 배지는 라벨 뒤에 badgeLabel이나 개수로 읽힙니다. 아이콘과 시각적 배지는 접근성 트리에서 빠집니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { BottomNavigation, Icon } from '@surflane/ui'
import { Link } from 'react-router'

// Pad the scrolling content so the bar never covers its last line.
<>
  <main
    style={{
      paddingBlockEnd:
        'calc(var(--surf-size-bottom-navigation) + env(safe-area-inset-bottom))',
    }}
  >
    Page content
  </main>
  <BottomNavigation.Root aria-label='Primary'>
    <BottomNavigation.Item
      render={<Link to='/runs' />}
      icon={<Icon name='play' />}
      label='Runs'
      current
    />
    <BottomNavigation.Item
      render={<Link to='/activity' />}
      icon={<Icon name='clock' />}
      label='Activity'
      badge={3}
      badgeLabel='3 unread'
    />
    <BottomNavigation.Item
      render={<Link to='/account' />}
      icon={<Icon name='user' />}
      label='Account'
    />
  </BottomNavigation.Root>
</>

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰