React contracts

Public type contracts, context values, provider props, link props, outlet props, fallback props, hook options, and generated registration types exported by @cookbook/router-react.

This page documents the public type contracts exported from the @cookbook/router-react root entrypoint.

It is not a usage guide. It is the map of what the React package commits to exporting.

@cookbook/router-react also exposes focused subpaths:

'@cookbook/router-react/hooks'
'@cookbook/router-react/links'
'@cookbook/router-react/outlets'
'@cookbook/router-react/provider'

Those subpaths re-export smaller surfaces. This page is scoped to the root React contract surface unless stated otherwise.

Link contracts

`LinkPrefetch`

type LinkPrefetch =
  | false
  | 'hover'
  | 'focus'
  | 'interaction'
  | 'mount';

Controls speculative route preloading for Link and NavLink.

Value	Meaning
`false`	No speculative preload.
`'hover'`	Preload on pointer enter.
`'focus'`	Preload on focus.
`'interaction'`	Preload on pointer enter or focus.
`'mount'`	Preload once for the resolved href while mounted.

`LinkProps<Route>`

interface LinkProps<Route extends RouteId = RouteId>
  extends Omit<
    AnchorHTMLAttributes<HTMLAnchorElement>,
    'href'
  > {
  readonly route?: Route;
  readonly to?: Route;
  readonly href?: string;
  readonly params?: HrefOptions<Route>['params'];
  readonly search?: HrefOptions<Route>['search'];
  readonly hash?: HrefOptions<Route>['hash'];
  readonly url?: HrefOptions<Route>['url'];
  readonly intercept?: InterceptInput | false;
  readonly context?: HrefOptions<Route>['context'];
  readonly preventScrollReset?: boolean;
  readonly replace?: boolean;
  readonly prefetch?: LinkPrefetch;
  readonly children?: ReactNode;
}

Prop

Type

LinkProps inherits all anchor attributes except href, because href is controlled by the router-aware contract.

NavLink contracts

`NavLinkEndOptions`

interface NavLinkEndOptions {
  readonly search?: 'all' | 'ignore';
}

Prop

Type

`NavLinkEnd`

type NavLinkEnd =
  | boolean
  | NavLinkEndOptions;

Controls active matching strictness for NavLink.

Value	Meaning
`false` or omitted	Allows prefix path matches.
`true`	Requires the full href to match.
`{ search: 'all' }`	Requires pathname, search, and hash to match.
`{ search: 'ignore' }`	Ignores search while comparing pathname and hash.

`NavLinkRenderProps`

interface NavLinkRenderProps {
  readonly isActive: boolean;
}

Prop

Type

`NavLinkProps<Route>`

interface NavLinkProps<Route extends RouteId = RouteId>
  extends Omit<
    AnchorHTMLAttributes<HTMLAnchorElement>,
    'children' | 'href'
  > {
  readonly route?: Route;
  readonly to?: Route;
  readonly href?: string;
  readonly params?: HrefOptions<Route>['params'];
  readonly search?: HrefOptions<Route>['search'];
  readonly hash?: HrefOptions<Route>['hash'];
  readonly url?: HrefOptions<Route>['url'];
  readonly replace?: boolean;
  readonly intercept?: false | InterceptInput;
  readonly context?: HrefOptions<Route>['context'];
  readonly preventScrollReset?: boolean;
  readonly prefetch?: LinkPrefetch;
  readonly end?: NavLinkEnd;
  readonly children?:
    | ReactNode
    | ((props: NavLinkRenderProps) => ReactNode);
}

Prop

Type

NavLinkProps inherits anchor attributes except href and children, because both are router-aware.

Outlet and slot contracts

`OutletProps<T>`

interface OutletProps<T = unknown> {
  readonly context?: T;
  readonly children?: ReactNode;
}

Prop

Type

`SlotErrorFallbackProps`

interface SlotErrorFallbackProps {
  readonly error: unknown;
  readonly reset: () => void;
}

Prop

Type

`SlotErrorFallback`

type SlotErrorFallback =
  | ComponentType<SlotErrorFallbackProps>
  | null;

Controls slot-local render-error isolation.

Value	Behavior
omitted	Slot render errors bubble to the nearest route, layout, or provider boundary.
`ComponentType<SlotErrorFallbackProps>`	Slot render errors are isolated and rendered by the fallback component.
`null`	Slot render errors are isolated and render nothing.

`SlotProps<T>`

interface SlotProps<T = unknown> {
  readonly name: string;
  readonly context?: T;
  readonly errorFallback?: SlotErrorFallback;
}

Prop

Type

Slot error fallback contracts are not route error fallback contracts. Treating them as interchangeable makes the wrong part of the UI disappear.

Lazy view contract

`LazyRouteViewComponent<Component>`

interface LazyRouteViewComponent<
  Component extends ComponentType<any> = ComponentType<any>,
> extends LazyExoticComponent<Component> {
  readonly preload: () => Promise<{
    readonly default: Component;
  }>;
}

Prop

Type

LazyRouteViewComponent is the return type of lazyRouteView().

Provider contracts

`RouterScrollBehavior`

type RouterScrollBehavior = ScrollBehavior;

Public alias for DOM scroll behavior accepted by provider-managed scroll restoration.

Common browser values:

'auto' | 'instant' | 'smooth'

`RouterProviderProps`

interface RouterProviderProps {
  readonly router: Router;
  readonly autoStart?: boolean;
  readonly children?: ReactNode;
  readonly fallback?: ReactNode;
  readonly loadingFallback?: ReactNode;
  readonly errorFallback?: ComponentType<RouterErrorFallbackProps>;
  readonly middleware?: readonly Middleware[];
  readonly scrollRestoration?: boolean;
  readonly scrollBehavior?: RouterScrollBehavior;
}

Prop

Type

`StaticRouterProviderProps`

interface StaticRouterProviderProps {
  readonly router: Router;
  readonly children?: ReactNode;
  readonly fallback?: ReactNode;
  readonly loadingFallback?: ReactNode;
  readonly errorFallback?: ComponentType<RouterErrorFallbackProps>;
  readonly middleware?: readonly Middleware[];
}

Prop

Type

StaticRouterProvider requires a started router. It does not expose autoStart, scrollRestoration, or scrollBehavior.

Render-helper contracts

`RenderReactRouteMatchOptions`

interface RenderReactRouteMatchOptions {
  readonly loadingFallback?: ReactNode;
  readonly errorFallback?: ComponentType<RouterErrorFallbackProps>;
  readonly error?: unknown;
}

Prop

Type

`RouteLoadingFallbackProps`

interface RouteLoadingFallbackProps {
  readonly route: MatchedRoute;
}

Prop

Type

`RouteErrorFallbackProps`

interface RouteErrorFallbackProps {
  readonly error: unknown;
  readonly reset: () => void;
  readonly route: MatchedRoute;
}

Prop

Type

`RouterErrorFallbackProps`

interface RouterErrorFallbackProps {
  readonly error: unknown;
  readonly reset: () => void;
  readonly route?: MatchedRoute;
}

Prop

Type

route is optional because startup errors and unmatched router errors may not have an active route.

Context contracts

`RouterContextValue`

interface RouterContextValue {
  readonly router: Router;
  readonly state: RouterState;
}

Prop

Type

`OutletContextValue`

interface OutletContextValue {
  readonly context?: unknown;
}

Prop

Type

`RouteRenderContextValue`

interface RouteRenderContextValue {
  readonly match: MatchedRoute;
}

Prop

Type

`SlotRenderContextValue`

interface SlotRenderContextValue {
  readonly ownerRouteId: string;
  readonly slots: Readonly<Record<string, ReactNode>>;
  readonly renderOptions?: RenderReactRouteMatchOptions;
}

Prop

Type

Public context values

The root entrypoint exports these React context values:

const RouterContext:
  Context<RouterContextValue | null>;

const OutletContext:
  Context<OutletContextValue | null>;

const RouteRenderContext:
  Context<RouteRenderContextValue | null>;

const SlotRenderContext:
  Context<SlotRenderContextValue | null>;

They are public for framework integrations and advanced rendering adapters. Application code should prefer hooks and components.

Internal contexts are not root exports.

Not public:

OutletRenderContext
SlotErrorIsolationContext

Not public:

useOutletContextValue
useOutletRenderContextValue
useRouteRenderContext
useSlotRenderContext

Hook option and result contracts

`UseBlockerOptions`

interface UseBlockerOptions {
  readonly when: boolean;
  readonly message?: string;
}

Prop

Type

`BlockerState`

interface BlockerState {
  readonly blocked: boolean;
}

Prop

Type

blocked is not a history of the last blocked transition. It is current hook state.

`OutletContextOptions`

interface OutletContextOptions {
  readonly strict?: boolean;
}

Prop

Type

`UseRouteMetaOptions`

interface UseRouteMetaOptions {
  readonly includeAncestors?: boolean;
  readonly merge?: false | RouteMetaMergeInput;
}

Prop

Type

Generated registration contracts

`Register`

interface Register {}

Register is the module augmentation target for generated React route contracts.

Prop

Type

The base interface is intentionally empty. Generated register.d.ts augments it.

`RouterContracts`

interface RouterContracts extends CoreRouterContracts {}

RouterContracts is the React package alias for the core generated contract model.

Prop

Type

The exact fields are supplied by generated core contracts. React consumes the same model for links, hooks, outlet context, and route metadata.

`RegisteredContracts`

type RegisteredContracts =
  Register extends {
    readonly contracts: infer Contracts;
  }
    ? Contracts
    : RouterContracts;

RegisteredContracts resolves to generated contracts when Register has been augmented. Otherwise it falls back to the base RouterContracts shape.

This is the type-level switch that makes route IDs, params, search, hash, metadata, and outlet context narrow after generated registration is included by TypeScript.

Root type export inventory

The @cookbook/router-react root entrypoint exports these public type names:

LinkPrefetch
LinkProps

LazyRouteViewComponent

NavLinkEnd
NavLinkEndOptions
NavLinkProps
NavLinkRenderProps

OutletProps

RenderReactRouteMatchOptions
RouteErrorFallbackProps
RouteLoadingFallbackProps
RouterErrorFallbackProps
RouterProviderProps
RouterScrollBehavior

StaticRouterProviderProps

SlotErrorFallback
SlotErrorFallbackProps
SlotProps

OutletContextValue
RouteRenderContextValue
SlotRenderContextValue
RouterContextValue

BlockerState
UseBlockerOptions
OutletContextOptions
UseRouteMetaOptions

Register
RegisteredContracts
RouterContracts

The root entrypoint exports these public context values:

RouterContext
OutletContext
RouteRenderContext
SlotRenderContext

The root entrypoint also exports useRouterContext, but the hook itself is documented with provider APIs, not contract types.

Register
RegisteredContracts
RouterContracts

from that file.

Do not document the rest as root exports unless packages/router-react/src/index.ts exports them.

Slot fallbacks are their own contract

SlotErrorFallbackProps is not RouteErrorFallbackProps.

Slot error fallback:

interface SlotErrorFallbackProps {
  readonly error: unknown;
  readonly reset: () => void;
}

Route error fallback:

interface RouteErrorFallbackProps {
  readonly error: unknown;
  readonly reset: () => void;
  readonly route: MatchedRoute;
}

That missing route is intentional. A slot-local boundary is not the route boundary.

Generated registration must reach TypeScript

Runtime routing does not prove contracts are active.

If generated register.d.ts is not included by TypeScript, React APIs still run, but route IDs, params, search, hash, metadata, and outlet context lose their generated precision.

On this page