clear-react-router 1.9.5 → 1.9.6

package/README.md

@@ -107,7 +107,7 @@ Component for client-side navigation with prefetch support, active state detecti
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `to` | `string` | required | Target path |
-| `as` | `(props: ElementProps<T>) => ReactElement` | renders `<a>` | Render prop for using a custom element/component instead of the default `<a>`. Receives the computed isActive and isPending values, event handlers, and ref to attach to your own element |
+| `as` | `(props: ElementProps<T>, state: { isActive: boolean; isPending: boolean }) => ReactElement` | renders `<a>` | Render function for using a custom element/component instead of the default <a>. Receives the props to spread onto your element (href, ref, event handlers, className, style, children) as the first argument, and `{ isActive, isPending }` as a separate second argument — kept separate so these values are never accidentally forwarded to the DOM |
 | `exact` | `boolean` | `false` | When `false`, the link is also considered active if the current URL starts with `to` (useful for nested routes) |
 | `prefetch` | `'hover' \| 'render' \| 'viewport' \| 'none'` | `Router` config | Override the global prefetch strategy |
 | `hoverPrefetchDelay` | `number` | `Router` config | Override the global hover delay |
@@ -134,27 +134,68 @@ Component for client-side navigation with prefetch support, active state detecti
 | `'viewport'` | Prefetches when the link enters the viewport (using Intersection Observer) |
 | `'none'` | No prefetching |
 
+### Custom elements via `as`
+
+When using `as` to render a custom component instead of the default `<a>`, your component **must spread all received props onto the underlying host element** — including `ref`. If any prop is dropped, the corresponding feature silently stops working (no error is thrown):
+
+- Missing `ref` → `viewport` prefetch never triggers (the `IntersectionObserver` has nothing to observe).
+- Missing `onClick` → navigation doesn't happen, the link just does nothing.
+- Missing `onMouseEnter`/`onMouseLeave` → `hover` prefetch doesn't trigger.
+- Missing `href` → the link isn't reachable via keyboard, screen readers, "open in new tab", etc.
+
+```tsx
+// ✅ correct — every prop is forwarded to the host element
+const Button = ({ children, ...props }: ElementProps<HTMLButtonElement>) => (
+  <button {...props}>{children}</button>
+);
+
+// ❌ wrong — ref, event handlers, and href are silently dropped
+const Button = ({ children }: { children: ReactNode }) => (
+  <button>{children}</button>
+);
+```
+
+If you only want to add or override specific props (e.g. add a `variant`), spread the received props first, then apply your own on top:
+
+```tsx
+const Button = ({ children, ...props }: ElementProps<HTMLButtonElement>) => (
+  <button {...props} className={`btn ${props.className ?? ''}`}>
+    {children}
+  </button>
+);
+```
+
+> **Note:** Because `as` is called as a plain function rather than rendered via JSX, avoid using React hooks (`useState`, `useEffect`, etc.) inside the function you pass to `as` — it isn't tracked by React as a separate component in the fiber tree. A function written for `as` (like `Button` above, which takes a second `state` argument) also isn't a valid standalone React component and shouldn't be rendered directly as `<Button />` elsewhere.
+
 **Example:**
 
 ```tsx
-import { Router, Link } from 'clear-react-router';
+import { Link, type ElementProps } from 'clear-react-router';
+
+const Button = (
+  { children, ...rest }: ElementProps<HTMLButtonElement>,
+  { isActive }: { isActive: boolean }
+) => (
+  <button {...rest} style={{ background: isActive ? 'tomato' : 'green' }}>
+    {children}
+  </button>
+);
+
+<Link to="/about" as={Button}>To about page</Link>
+
+For third-party components (MUI, Chakra, etc.), wrap them in an inline arrow function — most of them accept a
+single `props` argument and forward it to the host element themselves:
 
-// Render a custom element/component via `as`. The function receives ref, event handlers, isActive/isPending and must render them itself
 import { Button } from '@mui/material';
 
 <Link
-  to="/dashboard"
-  as={({ isActive, isPending, ...props }) => (
-    <Button
-      {...props}
-      variant={isActive ? 'contained' : 'outlined'}
-      sx={{ opacity: isPending ? 0.5 : 1 }}
-    />
-  )}
+  to="/about"
+  as={(props, { isActive }) => <Button {...props} variant={isActive ? 'contained' : 'text'} />}
 >
-  Dashboard
+  To about page
 </Link>
-
+```
+```tsx
 // Global prefetch: hover with 100ms delay
 <Router routes={routes} prefetch="hover" hoverPrefetchDelay={100} />
 

package/dist/components/Link.d.ts

@@ -1,32 +1,20 @@
-import { type CSSProperties, ReactNode, MouseEvent, ReactElement, Ref } from 'react';
-import { RouterProps } from '../types';
-type States = {
+import { type CSSProperties, ReactNode, ReactElement } from 'react';
+import { ElementProps, RouterProps } from '../types';
+type ElementState = {
     isActive: boolean;
     isPending: boolean;
 };
-type ElementProps<T extends HTMLElement = HTMLElement> = {
-    ref: Ref<T>;
-    href: string;
-    isActive: boolean;
-    isPending: boolean;
-    onClick(event: MouseEvent): void;
-    onMouseEnter(event: MouseEvent): void;
-    onMouseLeave(event: MouseEvent): void;
-    className?: string;
-    style?: CSSProperties;
-    children?: ReactNode;
-};
 type LinkProps<T extends HTMLElement = HTMLAnchorElement> = {
     to: string;
     children?: ReactNode;
-    as?: (props: ElementProps<T>) => ReactElement;
+    as?: (props: ElementProps<T>, state: ElementState) => ReactElement;
     prefetch?: RouterProps['prefetch'];
     hoverPrefetchDelay?: number;
-    className?: string | ((arg: States) => string);
+    className?: string | ((arg: ElementState) => string);
     activeClassName?: string;
     pendingClassName?: string;
     beforeNavigate?(): Promise<void>;
-    style?: CSSProperties | ((arg: States) => CSSProperties);
+    style?: CSSProperties | ((arg: ElementState) => CSSProperties);
     exact?: boolean;
 };
 export declare const Link: <T extends HTMLElement = HTMLAnchorElement>({ children, to, as, prefetch: prefetchLink, hoverPrefetchDelay, className, style, beforeNavigate, exact, activeClassName, pendingClassName, }: LinkProps<T>) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/index.d.ts

@@ -12,4 +12,4 @@ export { useRouterContext } from './hooks/useRouterContext';
 export { useSearchParams } from './hooks/useSearchParams';
 export { useFormContext } from './hooks/useFormContext';
 export { createRouter } from './utils/utils';
-export type { RouteItem, BlockerState, Location, RouterProps } from './types';
+export type { RouteItem, BlockerState, Location, RouterProps, ElementProps } from './types';

package/dist/index.js

@@ -757,7 +757,7 @@ var useLocation = () => {
 };
 //#endregion
 //#region components/Link.tsx
-var defaultAs = ({ isActive, isPending, ...props }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", { ...props });
+var defaultAs = (props) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("a", { ...props });
 var Link = ({ children, to, as = defaultAs, prefetch: prefetchLink, hoverPrefetchDelay, className, style, beforeNavigate, exact = false, activeClassName = "active-link", pendingClassName = "pending-link" }) => {
 	const isPending = useIsRoutePending(to);
 	const { pathname } = useLocation();
@@ -832,9 +832,10 @@ var Link = ({ children, to, as = defaultAs, prefetch: prefetchLink, hoverPrefetc
 		onClick: clickHandler,
 		onMouseEnter,
 		onMouseLeave,
-		isActive,
-		isPending,
 		children
+	}, {
+		isActive,
+		isPending
 	});
 };
 //#endregion

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, Dispatch, ReactElement, ReactNode, SetStateAction } from 'react';
+import { ComponentType, type CSSProperties, Dispatch, MouseEvent, ReactElement, ReactNode, Ref, SetStateAction } from 'react';
 import { Store, useGlobalState } from './create';
 import { Cell } from './cell';
 export type LazyComponent = () => Promise<{
@@ -154,4 +154,14 @@ export type InvalidateResult = {
     path: string;
     data: unknown;
 };
+export type ElementProps<T extends HTMLElement = HTMLElement> = {
+    ref: Ref<T>;
+    href: string;
+    className?: string;
+    style?: CSSProperties;
+    onClick(event: MouseEvent): void;
+    onMouseEnter(event: MouseEvent): void;
+    onMouseLeave(event: MouseEvent): void;
+    children?: ReactNode;
+};
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clear-react-router",
-  "version": "1.9.5",
+  "version": "1.9.6",
   "description": "A lightweight, type-safe routing library for React applications",
   "author": "Andrew Bubnov",
   "scripts": {