React와 Next.js 애플리케이션에서 스택 기반 전환을 쉽게 구현할 수 있는 경량 라이브러리입니다. 페이지 전환, 일부 컴포넌트 전환, 스와이프 UI 등 다양한 상황에 유연하게 적용할 수 있습니다.
📦 패키지 링크
J-React-Stack은 부드러운 전환 애니메이션과 직관적인 API를 제공하여 복잡한 상태 관리 없이 자연스러운 화면 전환을 구현할 수 있도록 돕습니다. 전체 페이지 전환은 물론, 폼 단계 이동, 스와이프 인터페이스, 모달/탭 전환 등 다양한 형태로 활용할 수 있습니다.
React Router나 Next.js 라우팅 시스템과 병행 사용이 가능하며, 필요한 페이지나 컴포넌트 일부에만 선택적으로 적용할 수 있습니다.
이 문서에서는 설치 방법, 기본 사용법, 고급 설정 방법까지 안내합니다.
npm install j-react-stack
# 또는
yarn add j-react-stack- 🎞 부드러운 전환 애니메이션
- 🧭 간단한 push/pop 네비게이션 API
- 💡 TypeScript 완벽 지원
- 🛠 초기 화면 필수 설정으로 안정성 확보
- 🎨 Tailwind CSS 손쉬운 통합
- 🔄 React와 Next.js(App Router 포함) 모두 지원
- 🧩 React Router 등 기존 라우터와 병행 사용 가능
- 📱 스와이프 기반 전환도 구현 가능
스택 기반 화면 전환을 위한 컨테이너 컴포넌트입니다. 페이지 내에서 컴포넌트 간 전환 애니메이션을 제공합니다.
import { StackNavigation } from "j-react-stack";
import FormStep1 from "./FormStep1";
export default function FormContainer() {
return (
<div className="form-container">
<h1>다단계 양식</h1>
<StackNavigation
initialStack={[{ key: "step1", element: <FormStep1 /> }]}
transitionDuration={300}
transitionTimingFunction="ease-in-out"
/>
</div>
);
}참고: initialStack에는 최소 하나 이상의 화면을 설정해야 정상 동작합니다.
스택 내 화면 전환을 제어하는 커스텀 훅입니다.
"use client"; // Next.js App Router 사용 시 필요
import { useStackNavigation } from "j-react-stack";
import FormStep2 from "./FormStep2";
function FormStep1() {
const { push, pop, clear, stack } = useStackNavigation();
const handleNextStep = () => {
// 양식 검증 후 다음 단계로 전환
push({ key: "step2", element: <FormStep2 /> });
};
return (
<div className="form-step">
<h2>1단계: 기본 정보</h2>
<input type="text" placeholder="이름" />
<input type="email" placeholder="이메일" />
<button onClick={handleNextStep}>다음 단계</button>
</div>
);
}| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| initialStack | StackItem[] | ✅ | - | 초기 스택 화면 배열 |
| transitionDuration | number | ❌ | 300 | 전환 애니메이션 시간(ms) |
| transitionTimingFunction | string | ❌ | "ease-in-out" | 전환 애니메이션 이징 함수 |
| className | string | ❌ | "" | 추가 스타일 클래스 |
| 메서드 | 설명 |
|---|---|
| push(item) | 새로운 화면을 스택에 추가 |
| pop() | 현재 화면 제거 후 이전 화면으로 이동 |
| clear() | 스택을 초기 상태로 리셋 |
| stack | 현재 스택 상태 조회 (배열 형태) |
- 회원가입 단계 UI
- 설문/투표 플로우
- 체크아웃 단계 (구매 플로우)
- 온보딩 튜토리얼
- 멀티스텝 폼
- 스와이프 기반 콘텐츠 탐색
- 페이지 내 일부 영역 전환
- React Router 사용 중 특정 섹션에만 스택 적용
J-React-Stack은 React Router와 함께 사용할 수 있습니다. React Router는 페이지 간 전환을 담당하고, J-React-Stack은 페이지 내에서 컴포넌트 간 전환을 담당합니다.
// App.tsx - React Router로 전체 앱 라우팅 구성
import { BrowserRouter, Routes, Route } from "react-router-dom";
import HomePage from "./HomePage";
import ProfilePage from "./ProfilePage";
import CheckoutPage from "./CheckoutPage";
export default function App() {
return (
<BrowserRouter>
<Routes>
<Route path="/" element={<HomePage />} />
<Route path="/profile" element={<ProfilePage />} />
<Route path="/checkout" element={<CheckoutPage />} />
</Routes>
</BrowserRouter>
);
}// CheckoutPage.tsx - 페이지 내에서 J-React-Stack으로 스텝 전환 구현
import { StackNavigation } from "j-react-stack";
import DeliveryInfoStep from "./steps/DeliveryInfoStep";
export default function CheckoutPage() {
return (
<div className="checkout-container">
<h1>결제 프로세스</h1>
{/* 페이지 내에서 J-React-Stack으로 다단계 프로세스 구현 */}
<StackNavigation
initialStack={[
{
key: "delivery",
element: <DeliveryInfoStep />,
},
]}
className="bg-white p-4 rounded-lg shadow-md"
/>
</div>
);
}// steps/DeliveryInfoStep.tsx - 스택 내 첫 번째 화면
import { useStackNavigation } from "j-react-stack";
import PaymentStep from "./PaymentStep";
export default function DeliveryInfoStep() {
const { push } = useStackNavigation();
const handleContinue = () => {
// 배송 정보 검증 후 결제 단계로 전환
push({ key: "payment", element: <PaymentStep /> });
};
return (
<div className="step-container">
<h2>1. 배송 정보</h2>
<form>
<input type="text" placeholder="주소" className="w-full mb-2" />
<input type="text" placeholder="연락처" className="w-full mb-4" />
<button
type="button"
onClick={handleContinue}
className="bg-blue-500 text-white px-4 py-2 rounded"
>
결제 정보 입력
</button>
</form>
</div>
);
}이 예제에서 React Router는 /checkout과 같은 URL 기반 페이지 이동을 처리하고, J-React-Stack은 체크아웃 페이지 내에서 배송 정보 → 결제 정보 → 주문 확인과 같은 단계별 UI 전환을 처리합니다.
"use client";
import { StackNavigation } from "j-react-stack";
export default function NextJsPage() {
return (
<StackNavigation
initialStack={[{ key: "home", element: <HomeScreen /> }]}
className="bg-white dark:bg-gray-800 rounded-xl shadow-md"
/>
);
}"use client";
import { useStackNavigation } from "j-react-stack";
function ClientComponent() {
const { push, pop } = useStackNavigation();
}모든 컴포넌트에 'use client' 지시문이 내장되어 있으므로 Pages Router와 App Router 모두 동일한 import 방식을 사용합니다.
<StackNavigation
initialStack={[{ key: "home", element: <HomeScreen /> }]}
className="bg-white dark:bg-gray-800 shadow-md rounded-lg overflow-hidden"
/>또는 StackRenderer를 직접 스타일링할 수 있습니다.
import { StackRenderer } from "j-react-stack";
<StackRenderer className="bg-white dark:bg-slate-800 rounded-xl shadow-lg" />;<StackNavigation
initialStack={[{ key: "home", element: <HomeScreen /> }]}
transitionDuration={500}
transitionTimingFunction="cubic-bezier(0.68, -0.55, 0.27, 1.55)"
/>- StackNavigation: 네비게이션 컨텍스트 및 화면 렌더링
- useStackNavigation: 스택 조작용 커스텀 훅
- StackItem, Activity: TypeScript 타입 정의
Q. Next.js 서버 컴포넌트(Server Component)에서 사용할 수 있나요?
A. 사용할 수 없습니다. "use client";를 선언하고 클라이언트 컴포넌트에서 사용해야 합니다.
Q. transitionDuration 값을 너무 길게 설정하면 어떤 문제가 생기나요?
A. 전환 속도가 느려져 사용자 경험이 저하되고, 깜빡임(flicker) 현상이 발생할 수 있습니다.
Q. 초기 화면 없이 StackNavigation을 렌더링하면 어떻게 되나요?
A. initialStack이 비어 있으면 정상적으로 동작하지 않습니다. 최소 하나 이상의 화면을 설정해야 합니다.
MIT License