Notification Badge

아이콘, 버튼, 메뉴 등 UI 요소에 붙어 새로운 알림이나 읽지 않은 메시지 수를 알려주는 컴포넌트예요.

설치

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

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

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

components/ui/notification-badge.tsx

/** * @title Notification Badge * @description 아이콘, 버튼, 메뉴 등에 붙어 새로운 알림이나 읽지 않은 메시지 수를 알려주는 컴포넌트예요. */import * as React from 'react';import { Slot } from 'radix-ui';import { cva, type VariantProps } from 'class-variance-authority';import { cn } from '@/lib/utils';// SEED Rootage spec: notification-badge.yaml / qvism recipe: notification-badge.tsconst notificationBadgeVariants = cva(  [    'box-border inline-flex items-center justify-center',    'text-start normal-case no-underline antialiased',    'bg-bg-brand-solid text-fg-on-brand-solid',  ],  {    variants: {      size: {        large: 'min-h-[18px] min-w-[18px] rounded-full px-x1 py-0 text-t1-static font-bold',        small: 'size-[6px] rounded-full',      },    },    defaultVariants: {      size: 'large',    },  },);const notificationBadgePositionerVariants = cva(  'absolute bottom-auto left-auto box-border inline-flex items-center justify-center',  {    variants: {      attach: {        icon: 'translate-x-full -translate-y-full',        text: 'translate-x-full translate-y-0',      },      size: {        large: '',        small: '',      },    },    compoundVariants: [      { size: 'large', attach: 'icon', className: 'top-[14px] right-[8px]' },      { size: 'small', attach: 'icon', className: 'top-[7px] right-[7px]' },      { size: 'large', attach: 'text', className: '-right-[2px]' },      { size: 'small', attach: 'text', className: '-right-[2px]' },    ],    defaultVariants: {      size: 'large',      attach: 'icon',    },  },);type NotificationBadgeSize = NonNullable<VariantProps<typeof notificationBadgeVariants>['size']>;const NotificationBadgeSizeContext = React.createContext<NotificationBadgeSize | undefined>(undefined);export interface NotificationBadgeProps  extends React.ComponentProps<'span'>,    VariantProps<typeof notificationBadgeVariants> {  asChild?: boolean;}function NotificationBadge({ className, size, asChild = false, children, ...props }: NotificationBadgeProps) {  const contextSize = React.useContext(NotificationBadgeSizeContext);  const resolvedSize = size ?? contextSize ?? 'large';  const Comp = asChild ? Slot.Root : 'span';  return (    <Comp      data-slot="notification-badge"      data-size={resolvedSize}      className={cn(notificationBadgeVariants({ size: resolvedSize }), className)}      {...props}    >      {/* Small 사이즈는 라벨을 지원하지 않아요. */}      {resolvedSize === 'small' && !asChild ? null : children}    </Comp>  );}export interface NotificationBadgePositionerProps  extends React.ComponentProps<'span'>,    VariantProps<typeof notificationBadgePositionerVariants> {  asChild?: boolean;}/** * 기준 요소(position: relative) 안에서 Notification Badge 를 우측 상단에 고정 배치해요. * `size` 는 안쪽 NotificationBadge 에 그대로 전달돼요. */function NotificationBadgePositioner({  className,  attach,  size,  asChild = false,  ...props}: NotificationBadgePositionerProps) {  const Comp = asChild ? Slot.Root : 'span';  const resolvedSize = size ?? 'large';  return (    <NotificationBadgeSizeContext.Provider value={resolvedSize}>      <Comp        data-slot="notification-badge-positioner"        data-attach={attach ?? 'icon'}        className={cn(notificationBadgePositionerVariants({ attach, size: resolvedSize }), className)}        {...props}      />    </NotificationBadgeSizeContext.Provider>  );}export {  NotificationBadge,  NotificationBadgePositioner,  notificationBadgeVariants,  notificationBadgePositionerVariants,};

Anatomy

Notification Badge는 Large와 Small 사이즈로 구성돼요. Large는 숫자를 표기하는 Label과 이를 감싸는 Container로 이루어져 있고, Small은 라벨 없는 도트 형태예요.

기준 요소에 붙일 때는 NotificationBadgePositioner 로 감싸요. 기준 요소에는 position: relative(relative) 를 지정해야 해요.

Properties

Size	설명
Large	라벨을 포함해 구체적인 알림 수나 상태 정보를 제공해요. 세부 정보가 중요하고 충분한 공간이 있을 때 사용해요. 내부 라벨을 반드시 포함해야 해요.
Small	간결한 도트 형태로, 텍스트 없이 상태 변화만 표시해요. 알림의 존재 여부만 중요하거나 공간이 제한된 경우에 적합해요. 내부 라벨은 지원하지 않아요.

Attach

NotificationBadgePositioner 의 attach 로 붙일 대상을 정해요. icon 은 아이콘의 우측 상단에, text 는 텍스트의 오른쪽 끝에 고정된 간격으로 배치돼요. size 는 안쪽 Notification Badge에 그대로 전달돼요.

12채팅

With Button

아이콘 버튼에 붙여 알림 진입점을 만들 수 있어요. 버튼의 aria-label 에 알림 수를 함께 담아 스크린 리더 사용자도 알 수 있게 해요.

Guidelines

Notification Badge의 위치

Notification Badge는 일반적으로 우측 상단에 위치하며, Top Navigation, Bottom Navigation, Tabs 같은 다른 컴포넌트에 포함되어 사용돼요. 표시 위치는 컴포넌트 안에서 참조하는 요소에 따라 조금씩 다르게 설정되어 있어요.

위치와 크기는 UI 레이아웃과의 시각적 충돌을 고려해 고정되어 있으므로, 임의로 변경하지 않아요.

Notification Badge의 동작

Notification Badge는 읽지 않은 메시지나 확인하지 않은 알림처럼 핵심 상태가 있을 때만 표시해요.

사용자가 알림을 확인하거나 상호작용을 완료하면 Badge는 즉시 사라져 "알림이 처리됨"이라는 시각적 피드백을 제공해요.

Label 표시

Large Badge의 Label은 최대 4자(필요하면 "+" 기호 포함)로 제한돼요. 0은 표시하지 않아요.

999999+

Do· 최대 4자

숫자가 크면 "999+" 처럼 4자 이내로 줄여서 표시해요.

Don't· 숫자 0 표시

숫자 0은 표시하지 않아요. 알림이 없으면 Badge를 숨겨요.

Notification Badge 남용하지 않기

Badge는 강한 색상과 대비를 가지고 있어, 한 화면에 여러 개 표시되면 사용자에게 시각적 피로를 주고 정보 인지를 방해할 수 있어요. 화면 내 Badge 수는 최소화하고, 우선순위가 높은 알림에만 사용하는 것을 권장해요.

Do· 우선순위 높은 알림에만

가장 중요한 알림 하나에만 Badge를 보여줘요.

312

Don't· 여러 곳에 동시에

한 화면 안에서 Notification Badge를 남용하지 않아요.

/** * @title Notification Badge * @description 아이콘, 버튼, 메뉴 등에 붙어 새로운 알림이나 읽지 않은 메시지 수를 알려주는 컴포넌트예요. */ import * as React from 'react'; import { Slot } from 'radix-ui'; import { cva, type VariantProps } from 'class-variance-authority'; import { cn } from '@/lib/utils'; // SEED Rootage spec: notification-badge.yaml / qvism recipe: notification-badge.ts const notificationBadgeVariants = cva( [ 'box-border inline-flex items-center justify-center', 'text-start normal-case no-underline antialiased', 'bg-bg-brand-solid text-fg-on-brand-solid', ], { variants: { size: { large: 'min-h-[18px] min-w-[18px] rounded-full px-x1 py-0 text-t1-static font-bold', small: 'size-[6px] rounded-full', }, }, defaultVariants: { size: 'large', }, }, ); const notificationBadgePositionerVariants = cva( 'absolute bottom-auto left-auto box-border inline-flex items-center justify-center', { variants: { attach: { icon: 'translate-x-full -translate-y-full', text: 'translate-x-full translate-y-0', }, size: { large: '', small: '', }, }, compoundVariants: [ { size: 'large', attach: 'icon', className: 'top-[14px] right-[8px]' }, { size: 'small', attach: 'icon', className: 'top-[7px] right-[7px]' }, { size: 'large', attach: 'text', className: '-right-[2px]' }, { size: 'small', attach: 'text', className: '-right-[2px]' }, ], defaultVariants: { size: 'large', attach: 'icon', }, }, ); type NotificationBadgeSize = NonNullable<VariantProps<typeof notificationBadgeVariants>['size']>; const NotificationBadgeSizeContext = React.createContext<NotificationBadgeSize | undefined>(undefined); export interface NotificationBadgeProps extends React.ComponentProps<'span'>, VariantProps<typeof notificationBadgeVariants> { asChild?: boolean; } function NotificationBadge({ className, size, asChild = false, children, ...props }: NotificationBadgeProps) { const contextSize = React.useContext(NotificationBadgeSizeContext); const resolvedSize = size ?? contextSize ?? 'large'; const Comp = asChild ? Slot.Root : 'span'; return ( <Comp data-slot="notification-badge" data-size={resolvedSize} className={cn(notificationBadgeVariants({ size: resolvedSize }), className)} {...props} > {/* Small 사이즈는 라벨을 지원하지 않아요. */} {resolvedSize === 'small' && !asChild ? null : children} </Comp> ); } export interface NotificationBadgePositionerProps extends React.ComponentProps<'span'>, VariantProps<typeof notificationBadgePositionerVariants> { asChild?: boolean; } /** * 기준 요소(position: relative) 안에서 Notification Badge 를 우측 상단에 고정 배치해요. * `size` 는 안쪽 NotificationBadge 에 그대로 전달돼요. */ function NotificationBadgePositioner({ className, attach, size, asChild = false, ...props }: NotificationBadgePositionerProps) { const Comp = asChild ? Slot.Root : 'span'; const resolvedSize = size ?? 'large'; return ( <NotificationBadgeSizeContext.Provider value={resolvedSize}> <Comp data-slot="notification-badge-positioner" data-attach={attach ?? 'icon'} className={cn(notificationBadgePositionerVariants({ attach, size: resolvedSize }), className)} {...props} /> </NotificationBadgeSizeContext.Provider> ); } export { NotificationBadge, NotificationBadgePositioner, notificationBadgeVariants, notificationBadgePositionerVariants, };

/** * @title Notification Badge * @description 아이콘, 버튼, 메뉴 등에 붙어 새로운 알림이나 읽지 않은 메시지 수를 알려주는 컴포넌트예요. */import * as React from 'react';import { Slot } from 'radix-ui';import { cva, type VariantProps } from 'class-variance-authority';import { cn } from '@/lib/utils';// SEED Rootage spec: notification-badge.yaml / qvism recipe: notification-badge.tsconst notificationBadgeVariants = cva( [ 'box-border inline-flex items-center justify-center', 'text-start normal-case no-underline antialiased', 'bg-bg-brand-solid text-fg-on-brand-solid', ], { variants: { size: { large: 'min-h-[18px] min-w-[18px] rounded-full px-x1 py-0 text-t1-static font-bold', small: 'size-[6px] rounded-full', }, }, defaultVariants: { size: 'large', }, },);const notificationBadgePositionerVariants = cva( 'absolute bottom-auto left-auto box-border inline-flex items-center justify-center', { variants: { attach: { icon: 'translate-x-full -translate-y-full', text: 'translate-x-full translate-y-0', }, size: { large: '', small: '', }, }, compoundVariants: [ { size: 'large', attach: 'icon', className: 'top-[14px] right-[8px]' }, { size: 'small', attach: 'icon', className: 'top-[7px] right-[7px]' }, { size: 'large', attach: 'text', className: '-right-[2px]' }, { size: 'small', attach: 'text', className: '-right-[2px]' }, ], defaultVariants: { size: 'large', attach: 'icon', }, },);type NotificationBadgeSize = NonNullable<VariantProps<typeof notificationBadgeVariants>['size']>;const NotificationBadgeSizeContext = React.createContext<NotificationBadgeSize | undefined>(undefined);export interface NotificationBadgeProps extends React.ComponentProps<'span'>, VariantProps<typeof notificationBadgeVariants> { asChild?: boolean;}function NotificationBadge({ className, size, asChild = false, children, ...props }: NotificationBadgeProps) { const contextSize = React.useContext(NotificationBadgeSizeContext); const resolvedSize = size ?? contextSize ?? 'large'; const Comp = asChild ? Slot.Root : 'span'; return ( <Comp data-slot="notification-badge" data-size={resolvedSize} className={cn(notificationBadgeVariants({ size: resolvedSize }), className)} {...props} > {/* Small 사이즈는 라벨을 지원하지 않아요. */} {resolvedSize === 'small' && !asChild ? null : children} </Comp> );}export interface NotificationBadgePositionerProps extends React.ComponentProps<'span'>, VariantProps<typeof notificationBadgePositionerVariants> { asChild?: boolean;}/** * 기준 요소(position: relative) 안에서 Notification Badge 를 우측 상단에 고정 배치해요. * `size` 는 안쪽 NotificationBadge 에 그대로 전달돼요. */function NotificationBadgePositioner({ className, attach, size, asChild = false, ...props}: NotificationBadgePositionerProps) { const Comp = asChild ? Slot.Root : 'span'; const resolvedSize = size ?? 'large'; return ( <NotificationBadgeSizeContext.Provider value={resolvedSize}> <Comp data-slot="notification-badge-positioner" data-attach={attach ?? 'icon'} className={cn(notificationBadgePositionerVariants({ attach, size: resolvedSize }), className)} {...props} /> </NotificationBadgeSizeContext.Provider> );}export { NotificationBadge, NotificationBadgePositioner, notificationBadgeVariants, notificationBadgePositionerVariants,};

Notification Badge

설치Copy Anchor Link

수동 설치

AnatomyCopy Anchor Link

PropertiesCopy Anchor Link

SizeCopy Anchor Link

AttachCopy Anchor Link

With ButtonCopy Anchor Link

GuidelinesCopy Anchor Link

Notification Badge의 위치Copy Anchor Link

Notification Badge의 동작Copy Anchor Link

Label 표시Copy Anchor Link

Notification Badge 남용하지 않기Copy Anchor Link

PropsCopy Anchor Link

NotificationBadgeCopy Anchor Link

NotificationBadgePositionerCopy Anchor Link

On this page

설치

Anatomy

Properties

Size