화면 상단에 위치해 탐색 인터페이스를 제공하는 네비게이션 컴포넌트예요.

상품 상세

설치

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

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

radix-ui, class-variance-authority, lucide-react 를 설치하고 아래 코드를 components/ui/top-navigation.tsx 에 복사해요.

components/ui/top-navigation.tsx

/** * @title Top Navigation * @description 화면 상단에 위치해 뒤로가기·닫기, 제목, 보조 액션을 제공하는 네비게이션 바예요. */import * as React from 'react';import { Slot } from 'radix-ui';import { cva, type VariantProps } from 'class-variance-authority';import { ChevronLeft, X } from 'lucide-react';import { cn } from '@/lib/utils';// SEED Rootage spec: top-navigation.yaml, top-navigation-icon-button.yaml, top-navigation-text-button.yamltype TopNavigationTone = 'layer' | 'transparent';type TopNavigationTheme = 'ios' | 'android';const TopNavigationContext = React.createContext<{ tone: TopNavigationTone; theme: TopNavigationTheme }>({  tone: 'layer',  theme: 'ios',});const useTopNavigation = () => React.useContext(TopNavigationContext);const topNavigationVariants = cva('relative isolate flex h-[56px] w-full shrink-0 items-center px-x1_5', {  variants: {    tone: {      layer: 'bg-bg-layer-default text-fg-neutral',      transparent: 'bg-transparent text-palette-static-white',    },    theme: {      // iOS: 제목 가운데 정렬. main 과 left/right 사이 최소 간격 x2      ios: 'grid grid-cols-[minmax(0,1fr)_minmax(0,max-content)_minmax(0,1fr)] gap-x-x2',      // Android: 제목 왼쪽 정렬      android: 'flex',    },    gradient: {      true: '',      false: '',    },  },  compoundVariants: [    {      tone: 'transparent',      gradient: true,      // #000000 35% → 0%, 하단으로 x5 만큼 확장      className:        'before:pointer-events-none before:absolute before:inset-x-0 before:top-0 before:-bottom-x5 before:-z-10 before:bg-linear-to-b before:from-palette-static-black/35 before:to-transparent',    },  ],  defaultVariants: {    tone: 'layer',    theme: 'ios',    gradient: true,  },});export interface TopNavigationProps  extends React.ComponentProps<'header'>,    VariantProps<typeof topNavigationVariants> {  asChild?: boolean;}function TopNavigation({  className,  tone = 'layer',  theme = 'ios',  gradient = true,  asChild = false,  ...props}: TopNavigationProps) {  const Comp = asChild ? Slot.Root : 'header';  const value = React.useMemo(() => ({ tone: tone ?? 'layer', theme: theme ?? 'ios' }), [tone, theme]);  return (    <TopNavigationContext.Provider value={value}>      <Comp        data-slot="top-navigation"        data-tone={tone}        data-theme={theme}        className={cn(topNavigationVariants({ tone, theme, gradient }), className)}        {...props}      />    </TopNavigationContext.Provider>  );}function TopNavigationLeft({ className, ...props }: React.ComponentProps<'div'>) {  return (    <div      data-slot="top-navigation-left"      className={cn('col-start-1 flex h-full shrink-0 items-center justify-self-start', className)}      {...props}    />  );}function TopNavigationRight({ className, ...props }: React.ComponentProps<'div'>) {  return (    <div      data-slot="top-navigation-right"      className={cn('col-start-3 ml-auto flex h-full shrink-0 items-center justify-self-end', className)}      {...props}    />  );}export interface TopNavigationMainProps extends Omit<React.ComponentProps<'div'>, 'title'> {  /** 제목. children 을 넣으면 무시돼요. */  title?: React.ReactNode;  /** 부제목. 있으면 withSubtitle 레이아웃이 적용돼요. */  subtitle?: React.ReactNode;}function TopNavigationMain({ className, title, subtitle, children, ...props }: TopNavigationMainProps) {  const { theme } = useTopNavigation();  const layout = subtitle ? 'withSubtitle' : 'titleOnly';  return (    <div      data-slot="top-navigation-main"      data-layout={layout}      className={cn(        'col-start-2 flex min-w-0 flex-col justify-center',        theme === 'ios' ? 'items-center text-center' : 'flex-1 items-start pl-x1_5 text-left',        className,      )}      {...props}    >      {children ?? (        <>          <TopNavigationTitle layout={layout}>{title}</TopNavigationTitle>          {subtitle ? <TopNavigationSubtitle>{subtitle}</TopNavigationSubtitle> : null}        </>      )}    </div>  );}const topNavigationTitleVariants = cva('max-w-full truncate font-bold', {  variants: {    layout: {      titleOnly: 'text-t6',      withSubtitle: 'text-t5',    },  },  defaultVariants: { layout: 'titleOnly' },});function TopNavigationTitle({  className,  layout,  ...props}: React.ComponentProps<'h1'> & VariantProps<typeof topNavigationTitleVariants>) {  const { tone } = useTopNavigation();  return (    <h1      data-slot="top-navigation-title"      className={cn(        topNavigationTitleVariants({ layout }),        tone === 'layer' ? 'text-fg-neutral' : 'text-palette-static-white',        className,      )}      {...props}    />  );}function TopNavigationSubtitle({ className, ...props }: React.ComponentProps<'p'>) {  const { tone } = useTopNavigation();  return (    <p      data-slot="top-navigation-subtitle"      className={cn(        'max-w-full truncate text-t2 font-regular',        tone === 'layer' ? 'text-fg-neutral-muted' : 'text-palette-static-white',        className,      )}      {...props}    />  );}const buttonBase = [  'relative inline-flex shrink-0 cursor-pointer select-none items-center justify-center rounded-r2 bg-bg-transparent',  'transition-[background-color,scale,outline-color] duration-(--rb-duration-color-transition) ease-easing',  'outline-2 -outline-offset-2 outline-transparent focus-visible:outline-stroke-focus-ring',  'enabled:active:scale-[0.95] enabled:active:bg-bg-transparent-pressed',  'disabled:cursor-not-allowed disabled:text-fg-disabled',];export interface TopNavigationIconButtonProps extends React.ComponentProps<'button'> {  asChild?: boolean;}function TopNavigationIconButton({ className, asChild = false, type, ...props }: TopNavigationIconButtonProps) {  const { tone } = useTopNavigation();  const Comp = asChild ? Slot.Root : 'button';  return (    <Comp      data-slot="top-navigation-icon-button"      type={asChild ? undefined : (type ?? 'button')}      className={cn(        buttonBase,        'size-[44px] [&_svg]:pointer-events-none [&_svg]:size-[24px] [&_svg]:shrink-0',        tone === 'layer' ? 'text-fg-neutral' : 'text-palette-static-white',        className,      )}      {...props}    />  );}export interface TopNavigationTextButtonProps extends React.ComponentProps<'button'> {  asChild?: boolean;}function TopNavigationTextButton({ className, asChild = false, type, ...props }: TopNavigationTextButtonProps) {  const { tone, theme } = useTopNavigation();  const Comp = asChild ? Slot.Root : 'button';  return (    <Comp      data-slot="top-navigation-text-button"      type={asChild ? undefined : (type ?? 'button')}      className={cn(        buttonBase,        'h-[44px] px-x2_5 text-t5 font-medium',        theme === 'ios' && 'max-w-[96px]',        '[&>*]:truncate',        tone === 'layer' ? 'text-fg-neutral' : 'text-palette-static-white',        className,      )}      {...props}    />  );}function TopNavigationBackButton({ children, ...props }: TopNavigationIconButtonProps) {  return (    <TopNavigationIconButton aria-label="뒤로" {...props}>      {children ?? <ChevronLeft />}    </TopNavigationIconButton>  );}function TopNavigationCloseButton({ children, ...props }: TopNavigationIconButtonProps) {  return (    <TopNavigationIconButton aria-label="닫기" {...props}>      {children ?? <X />}    </TopNavigationIconButton>  );}export {  TopNavigation,  TopNavigationLeft,  TopNavigationMain,  TopNavigationRight,  TopNavigationTitle,  TopNavigationSubtitle,  TopNavigationIconButton,  TopNavigationTextButton,  TopNavigationBackButton,  TopNavigationCloseButton,  topNavigationVariants,};

Anatomy

Top Navigation은 Left, Main, Right 세 영역을 감싸는 Container로 구성돼요.

Left: 뒤로가기·닫기 버튼(TopNavigationBackButton, TopNavigationCloseButton)이 위치해요.
Main: Title과 Subtitle을 포함하는 영역이에요.
Right: Icon Button(TopNavigationIconButton) 또는 Text Button(TopNavigationTextButton)이 위치해요.

Top Navigation은 Root 타입과 Standard 타입 두 가지로 나뉘어요. Root 타입은 앱의 최상위 루트 탭에서, Standard 타입은 2-depth 이상의 화면에서 사용해요.

Properties

Title Type

Root Top Navigation의 Title 영역에는 Label만 표시하는 Text 타입과, 선택 시 동작이 있는 Button 타입을 선택해서 사용할 수 있어요. TopNavigationMain 에 children 을 넣으면 Title 영역을 자유롭게 구성할 수 있어요.

홈

Left Slot

Standard 타입 Top Navigation은 2-depth 이상의 화면에서 사용하며, 왼쪽에 네비게이션 액션을 배치할 수 있어요. 뒤로가기와 닫기 버튼은 서로 다른 동작을 제공하므로 각 버튼의 차이를 이해하고 정확한 용도에 맞게 사용해요.

뒤로가기

닫기

Right Slot

Top Navigation 우측에는 Icon Button 또는 Text Button을 배치할 수 있어요. Icon Button은 최대 3개까지 추가할 수 있으며, 타이틀 영역과 겹치지 않도록 개수를 조정해서 사용하는 것을 권장해요. Text Button은 1개만 표시할 수 있어요.

아이콘 버튼

글쓰기

Subtitle

subtitle 을 지정하면 Title은 t5, Subtitle은 t2 크기의 두 줄 레이아웃(withSubtitle)으로 바뀌어요. 타이틀은 한 줄로 표시되며, 길어지면 말줄임으로 표시돼요.

김콘마

보통 10분 이내 응답

제목이 아주 길어서 한 줄에 다 들어가지 않으면 말줄임으로 표시돼요

Layer와 Transparent 두 가지 Tone을 가져요. Transparent는 이미지 위에 Top Navigation을 띄울 때 사용하며, 기본으로 상단에서 아래로 옅어지는 그라디언트(검정 35% → 0%)를 깔아 콘텐츠 가독성을 확보해요. gradient={false} 는 권장하지 않아요. 스크린 배경 색이 보이길 원한다면 tone="layer" 에 className 으로 배경색을 바꿔 사용해요.

Layer

Transparent

Theme

iOS는 제목을 가운데 정렬하고 좌우 영역과 최소 x2 간격을 유지해요. Android는 제목을 왼쪽 정렬하고 x1_5 의 왼쪽 여백을 둬요.

iOS · 가운데 정렬

Android · 왼쪽 정렬

Notification Badge

Icon Button에 Notification Badge를 표시할 수 있어요. Small과 Large 사이즈 모두 사용할 수 있으며, Large 사이즈는 숫자 정보가 필요한 경우에 사용해요.

내 콘마켓

Guidelines

Root Top Navigation: 앱의 최상위 루트 탭에서 사용되며, 핵심 액션 진입을 제공해요.
Standard Top Navigation: 2-depth 이상의 화면에서 사용돼요. 뒤로가기 또는 닫기, 타이틀, 보조 액션을 통해 현재 위치와 주요 인터랙션을 안내해요.

뒤로가기(Back)와 닫기(Close) 동작

뒤로가기와 닫기는 비슷해 보이지만 서로 다른 동작을 제공해요. 사용자의 흐름에 큰 영향을 주므로 각 동작을 정확히 이해하고 사용하는 것이 중요해요.

구분	뒤로가기 (Back)	닫기 (Close)
이동 방식	이전 화면으로 이동	현재 레이어/플로우 종료
적용 위치	일반 페이지, 계층 구조 화면	모달, 독립 플로우
UX 의미	한 단계 뒤로 가기	이 플로우를 끝내고 나가기
아이콘	`<` (Chevron Left)	`X` (Close)
예상 행동	이전 단계 유지	현재 상태/입력 값이 폐기될 수 있음

뒤로가기 (Back)

네비게이션 스택을 기반으로 현재 화면을 이전 화면으로 되돌려요. 히스토리 기반(History Back)과 계층 기반(Hierarchy Back)으로 구분되며, 화면의 목적과 진입 경로에 따라 선택해서 사용해요.

계층적인 화면 구조에서 단계별 이동이 필요한 경우
사용자의 입력 내용을 유지해야 하는 경우

닫기 (Close)

현재 화면을 종료하고 상위 레이어로 복귀해요. 페이지 히스토리를 거슬러 올라가는 것이 아니라, 열려 있는 모달, Bottom Sheet, 전체 화면 등을 닫는 동작이에요.

모달/풀스크린 모달/Bottom Sheet처럼 레이어를 닫는 경우
상태를 초기화하거나, 플로우를 종료하거나, 작업을 중단하는 경우

History Back vs. Hierarchy Back

뒤로가기 버튼은 실제로는 History Back(히스토리 기반)과 Hierarchy Back(계층 기반)으로 구분돼요. 사용자가 예상치 못한 이동을 경험하지 않도록 일관된 정책을 적용해요.

구분	History Back	Hierarchy Back
기준	사용자의 실제 이동 경로	앱의 정보 구조 (IA)
이동 결과	직전 화면으로 이동	상위 레벨 화면으로 이동
외부 진입	외부로 다시 나갈 수도 있음	앱 내부 상위 화면으로 고정
대표 케이스	검색, 추천, 피드 기반 탐색	설정, 프로필, 고정 구조 메뉴

타이틀 작성하기

타이틀은 한 줄로 표시되도록 간결하게 작성해요. 액션 개수에 따라 타이틀 길이가 자동으로 조정되며, 길어지면 말줄임으로 표시돼요.

우측 액션 영역 사용하기

아이콘 버튼은 최대 2개까지 표시하는 것을 권장해요. 필요하면 3개까지 표시할 수 있지만, 타이틀 텍스트가 충분히 표시되지 않을 수 있으니 주의해요. 액션이 3개를 초과하면 더보기 버튼과 Menu Sheet를 조합해 중요한 액션만 노출하고 나머지는 숨겨요.

‹상품 상세⋮

Do· 액션은 2개 이하로

중요한 액션만 노출하고 나머지는 더보기 메뉴로 숨겨요.

‹아주 긴 상품 상세 제목♡ ⇪ ⋮ ⚙

Don't· 타이틀과 겹치는 액션

타이틀 영역과 우측 액션 영역이 겹치지 않도록 주의해요.

스크롤 시 동작

Top Navigation은 스크롤할 때 항상 상단에 고정되는 동작을 기본으로 가져요. 고정된 영역과 스크롤되는 영역을 구분하기 위한 별도의 시각적 장치는 표시하지 않아요. 배경이 투명한 Top Navigation은 스크롤할 때 배경색이 채워져요.

빈티지 원목 의자

아래로 스크롤하면 배경이 채워져요.

TopNavigationBackButton 과 TopNavigationCloseButton 은 아이콘과 aria-label("뒤로", "닫기")이 미리 지정된 TopNavigationIconButton 이에요.

Top Navigation

설치Copy Anchor Link

수동 설치

AnatomyCopy Anchor Link

PropertiesCopy Anchor Link

Title TypeCopy Anchor Link

Left SlotCopy Anchor Link

Right SlotCopy Anchor Link

SubtitleCopy Anchor Link

ToneCopy Anchor Link

ThemeCopy Anchor Link

Notification BadgeCopy Anchor Link

GuidelinesCopy Anchor Link

Root Top Navigation과 Standard Top Navigation의 차이Copy Anchor Link

뒤로가기(Back)와 닫기(Close) 동작Copy Anchor Link

뒤로가기 (Back)Copy Anchor Link

닫기 (Close)Copy Anchor Link

History Back vs. Hierarchy BackCopy Anchor Link

타이틀 작성하기Copy Anchor Link

우측 액션 영역 사용하기Copy Anchor Link

스크롤 시 동작Copy Anchor Link

PropsCopy Anchor Link

TopNavigationCopy Anchor Link

TopNavigationMainCopy Anchor Link

TopNavigationIconButton · TopNavigationTextButtonCopy Anchor Link

On this page

설치