@esmx/router-react
React integration for @esmx/router - A powerful router with React 18+ support using modern hooks and context patterns.
English | δΈζ
## π Features
β¨ **React 18+ Support** - Built for React 18 and 19 with hooks and concurrent features
π― **Hooks First** - Modern hook-based API with `useRouter`, `useRoute`, `useLink`
π **Seamless Integration** - Works with @esmx/router core
π **TypeScript Ready** - Full TypeScript support with excellent DX
β‘ **High Performance** - Uses `useSyncExternalStore` for optimal re-renders
π **SSR Compatible** - Server-side rendering support out of the box
π¦ **Lightweight** - Minimal bundle size with zero dependencies (except peer deps)
π§ **Pure TypeScript** - No JSX required, uses React.createElement for maximum compatibility
## π¦ Installation
```bash
# npm
npm install @esmx/router @esmx/router-react
# pnpm
pnpm add @esmx/router @esmx/router-react
# yarn
yarn add @esmx/router @esmx/router-react
```
## π Quick Start
```tsx
import { Router, RouterMode } from '@esmx/router';
import { RouterProvider, RouterView, RouterLink } from '@esmx/router-react';
// Define your routes
const routes = [
{ path: '/', component: () => import('./views/Home') },
{ path: '/about', component: () => import('./views/About') },
{ path: '/users/:id', component: () => import('./views/UserProfile') }
];
// Create router instance
const router = new Router({
routes,
mode: RouterMode.history
});
// Wrap your app with RouterProvider
function App() {
return (
);
}
export default App;
```
## π API Reference
### Components
#### RouterProvider
Provides router context to the React component tree. Must wrap your application.
```tsx
import { Router } from '@esmx/router';
import { RouterProvider } from '@esmx/router-react';
const router = new Router({ routes });
function App() {
return (
{/* Your app components */}
);
}
```
**Props:**
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `router` | `Router` | Yes | Router instance from @esmx/router |
| `children` | `ReactNode` | Yes | Child components |
#### RouterView
Renders the matched route component. Supports nested routing with automatic depth tracking.
```tsx
import { RouterView } from '@esmx/router-react';
function Layout() {
return (
);
}
```
**Props:**
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `fallback` | `ReactNode \| ComponentType` | - | Fallback content when no route matches |
**Nested Routing Example:**
```tsx
// Routes configuration
const routes = [
{
path: '/users',
component: UsersLayout,
children: [
{ path: '', component: UsersList },
{ path: ':id', component: UserProfile }
]
}
];
// UsersLayout.tsx - Contains nested RouterView
function UsersLayout() {
return (
Users Section
{/* Renders UsersList or UserProfile */}
);
}
```
#### RouterLink
A component for creating navigation links with active state management.
```tsx
import { RouterLink } from '@esmx/router-react';
function Navigation() {
return (
);
}
```
**Props:**
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `to` | `string \| RouteLocationInput` | - | Target route location |
| `type` | `RouterLinkType` | `'push'` | Navigation type |
| `exact` | `RouteMatchType` | `'include'` | Active matching mode |
| `activeClass` | `string` | - | CSS class for active state |
| `event` | `string \| string[]` | `'click'` | Events triggering navigation |
| `tag` | `string` | `'a'` | HTML tag to render |
| `layerOptions` | `RouterLayerOptions` | - | Layer navigation options |
| `beforeNavigate` | `function` | - | Callback before navigation |
| `children` | `ReactNode` | - | Link content |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties` | - | Inline styles |
**Navigation Types:**
- `'push'` - Add entry to history stack (default)
- `'replace'` - Replace current history entry
- `'pushWindow'` - Open in new window/tab
- `'replaceWindow'` - Replace current window location
- `'pushLayer'` - Open in layer (modal/dialog routing)
### Hooks
#### useRouter()
Get the router instance for programmatic navigation.
```tsx
import { useRouter } from '@esmx/router-react';
function NavigationControls() {
const router = useRouter();
const goHome = () => router.push('/');
const goBack = () => router.back();
const goForward = () => router.forward();
const goToUser = (id: string) => {
router.push({
path: '/users/:id',
params: { id }
});
};
const replaceRoute = () => {
router.replace('/login');
};
return (
);
}
```
#### useRoute()
Get the current route information (reactive).
```tsx
import { useRoute } from '@esmx/router-react';
import { useEffect } from 'react';
function CurrentRoute() {
const route = useRoute();
useEffect(() => {
console.log('Route changed:', route.path);
document.title = route.meta?.title || 'My App';
}, [route.path, route.meta?.title]);
return (
Path: {route.path}
Params: {JSON.stringify(route.params)}
Query: {JSON.stringify(route.query)}
Hash: {route.hash}
Meta: {JSON.stringify(route.meta)}
);
}
```
#### useLink()
Create reactive link helpers for custom navigation components.
```tsx
import { useLink } from '@esmx/router-react';
interface CustomNavButtonProps {
to: string;
children: React.ReactNode;
}
function CustomNavButton({ to, children }: CustomNavButtonProps) {
const link = useLink({ to, type: 'push', exact: 'include' });
return (
);
}
```
**Return Value (`RouterLinkResolved`):**
| Property | Type | Description |
|----------|------|-------------|
| `route` | `Route` | Resolved route object |
| `type` | `RouterLinkType` | Navigation type |
| `isActive` | `boolean` | Whether link matches current route |
| `isExactActive` | `boolean` | Whether link exactly matches current route |
| `isExternal` | `boolean` | Whether link points to external origin |
| `tag` | `string` | HTML tag to render |
| `attributes` | `RouterLinkAttributes` | HTML attributes (href, class, target, rel) |
| `navigate` | `(e: Event) => Promise` | Navigation function |
| `createEventHandlers` | `function` | Generate event handlers |
#### useRouterViewDepth()
Get the current RouterView depth (for advanced nested routing scenarios).
```tsx
import { useRouterViewDepth } from '@esmx/router-react';
function DebugView() {
const depth = useRouterViewDepth();
return Current depth: {depth}
;
}
```
### Context
#### RouterContext
Direct access to the router context (for advanced use cases).
```tsx
import { RouterContext } from '@esmx/router-react';
import { useContext } from 'react';
function CustomRouterConsumer() {
const context = useContext(RouterContext);
if (!context) {
return Not inside RouterProvider
;
}
const { router, route } = context;
// Use router and route directly
}
```
## Advanced Usage
### Route Guards
```tsx
import { useRouter, useRoute } from '@esmx/router-react';
import { useEffect } from 'react';
function AuthGuard({ children }: { children: React.ReactNode }) {
const router = useRouter();
const route = useRoute();
useEffect(() => {
// Register beforeEach guard
const unregister = router.beforeEach((to, from) => {
if (to.meta?.requiresAuth && !isAuthenticated()) {
return '/login';
}
});
return () => unregister();
}, [router]);
return <>{children};
}
```
### SSR Integration
```tsx
import { Router, RouterMode } from '@esmx/router';
import { RouterProvider, RouterView } from '@esmx/router-react';
import { renderToString } from 'react-dom/server';
async function renderApp(url: string) {
const router = new Router({
routes,
mode: RouterMode.history,
url // Pass the request URL
});
// Wait for route resolution
await router.push(url);
const html = renderToString(
);
return html;
}
```
### Custom Link Component with Additional Features
```tsx
import { useLink } from '@esmx/router-react';
import { forwardRef, type AnchorHTMLAttributes } from 'react';
interface NavLinkProps extends AnchorHTMLAttributes {
to: string;
icon?: React.ReactNode;
badge?: number;
}
export const NavLink = forwardRef(
({ to, icon, badge, children, className, ...props }, ref) => {
const link = useLink({ to, exact: 'include' });
return (
{
e.preventDefault();
link.navigate(e);
}}
className={`nav-link ${link.isActive ? 'active' : ''} ${className || ''}`}
aria-current={link.isExactActive ? 'page' : undefined}
{...props}
>
{icon && {icon}}
{children}
{badge !== undefined && badge > 0 && (
{badge}
)}
);
}
);
NavLink.displayName = 'NavLink';
```
## TypeScript Support
This package provides full TypeScript support. All types are exported and properly documented.
```tsx
import type {
RouterContextValue,
RouterProviderProps,
RouterViewProps,
RouterLinkComponentProps
} from '@esmx/router-react';
import type {
Route,
Router,
RouterLinkProps,
RouterLinkResolved,
RouteLocationInput
} from '@esmx/router';
```
## Browser Support
- **Modern browsers** that support ES modules (`import`/`export`) and React 18+
- Chrome 64+, Firefox 67+, Safari 11.1+, Edge 79+
## Contributing
We welcome contributions! Please feel free to submit issues and pull requests.
## π License
MIT Β© [Esmx Team](https://github.com/esmnext/esmx)
## Related Packages
- [@esmx/router](https://github.com/esmnext/esmx/tree/master/packages/router) - Core router package
- [@esmx/router-vue](https://github.com/esmnext/esmx/tree/master/packages/router-vue) - Vue integration
- [@esmx/core](https://github.com/esmnext/esmx/tree/master/packages/core) - Esmx core framework
