border-beam — React용 애니메이션 테두리 빔 효과

React 요소의 테두리를 따라 빛이 이동하거나 숨 쉬는 듯한 glow를 입히는 경량 UI 컴포넌트. 카드·버튼·입력창·검색창 같은 기존 콘텐츠를 감싸서 제품 UI에 시각적 강조를 추가한다.

무엇인가

border-beam은 Jakub Antalik이 만든 TypeScript/React 오픈소스 패키지다. BorderBeam 컴포넌트가 자식 요소를 감싸고, CSS pseudo-element·gradient·mask를 조합해 테두리 효과를 렌더링한다. 콘텐츠 자체의 레이아웃과 입력 동작은 건드리지 않고 장식 레이어만 추가한다.

2026-07-10 GitHub 스냅샷 기준으로 버전은 1.3.0, MIT 라이선스, TypeScript 프로젝트이며 저장소에는 약 1.1k stars와 64 forks가 표시된다. 최신 README는 React >=18을 peer dependency로 요구한다.

효과 프리셋

size가 효과의 움직임과 형태를 결정한다.

md: 전체 테두리를 도는 기본 traveling beam
sm: 작은 버튼·아이콘 등 컴팩트한 요소용
line: 하단 중심의 traveling glow
pulse-inner: 요소 안쪽에 갇힌 breathing glow
pulse-outside: 불투명한 자식 요소 뒤에서 바깥으로 퍼지는 halo

색상은 colorful(무지개), mono(단색/그레이스케일), ocean(블루·퍼플), sunset(오렌지·옐로·레드)을 제공한다. theme="dark" | "light" | "auto"로 배경에 맞는 강도와 색감을 선택할 수 있다.

주요 API

import { BorderBeam } from 'border-beam';
 
<BorderBeam size="md" colorVariant="ocean" theme="dark" strength={0.7}>
  <Card />
</BorderBeam>

duration: 회전·호흡 주기(초)
active: 애니메이션 on/off; fade-in/fade-out 콜백(onActivate, onDeactivate) 지원
borderRadius: 생략하면 첫 번째 자식의 border-radius를 자동 감지
brightness, saturation, hueRange, strength: glow의 시각적 강도와 색 변화 조정
staticColors: hue-shift 애니메이션 비활성화
표준 HTMLDivElement 속성, className, style, ref 전달 지원

구현상 특징

회전·line 효과는 CSS @property와 keyframe 애니메이션으로 빔의 위치, 폭, 높이, edge fade, spike를 조합한다.
pulse 효과는 여러 인스턴스가 각자 requestAnimationFrame을 돌리지 않도록 공유 드라이버를 사용하고, 약 30fps로 제한해 paint 빈도를 낮춘다.
IntersectionObserver로 화면 밖 인스턴스의 paint-heavy 애니메이션을 일시 정지한다.
prefers-reduced-motion: reduce를 존중하며, 효과 레이어에는 pointer-events: none을 사용해 콘텐츠의 클릭·키보드 조작을 방해하지 않는다.
pulse-outside는 자식이 불투명해야 바깥 halo가 의도대로 보이며, 주변 레이아웃에 glow가 퍼질 여유가 있어야 한다.

도입 판단

장점

npm install border-beam 후 래퍼 하나로 적용할 수 있는 낮은 도입 비용
카드·CTA·검색창 등에 제품 완성도와 시각적 주목도를 빠르게 추가
dark/light 테마, 색상 팔레트, 강도, 모션 선호도 대응이 한 컴포넌트에 포함
CSS 중심 렌더링과 offscreen pause로 장식 효과의 비용을 어느 정도 통제

주의점

테두리 glow는 정보 구조나 접근성을 개선하는 기능이 아니라 장식 효과이므로, 상태·오류·포커스 표현을 이 효과에만 의존하면 안 된다.
CSS mask, @property, filter, pseudo-element 조합에 의존하므로 지원 브라우저 범위를 제품 기준으로 확인해야 한다. 저장소 README는 Chrome 85+, Safari 15.4+, Firefox 128+를 요구사항으로 적고 있다.
pulse-outside는 overflow: hidden 부모에 의해 halo가 잘릴 수 있고, 투명한 자식에서는 내부 glow가 비쳐 의도와 달라질 수 있다.
단일 소스(README·공개 저장소) 기준 정리이므로 실제 번들 크기와 브라우저별 시각 차이는 도입 전에 직접 검증하는 편이 안전하다.

LLM Wiki

탐색기