UNPKG

12.8 kBTypeScriptView Raw
1import * as React from "react";
2import type { History, InitialEntry, Location, Path, To } from "history";
3import { Action as NavigationType } from "history";
4export type { Location, Path, To, NavigationType };
5/**
6 * A Navigator is a "location changer"; it's how you get to different locations.
7 *
8 * Every history instance conforms to the Navigator interface, but the
9 * distinction is useful primarily when it comes to the low-level <Router> API
10 * where both the location and a navigator must be provided separately in order
11 * to avoid "tearing" that may occur in a suspense-enabled app if the action
12 * and/or location were to be read directly from the history instance.
13 */
14export declare type Navigator = Pick<History, "go" | "push" | "replace" | "createHref">;
15interface NavigationContextObject {
16 basename: string;
17 navigator: Navigator;
18 static: boolean;
19}
20declare const NavigationContext: React.Context<NavigationContextObject>;
21interface LocationContextObject {
22 location: Location;
23 navigationType: NavigationType;
24}
25declare const LocationContext: React.Context<LocationContextObject>;
26interface RouteContextObject {
27 outlet: React.ReactElement | null;
28 matches: RouteMatch[];
29}
30declare const RouteContext: React.Context<RouteContextObject>;
31export interface MemoryRouterProps {
32 basename?: string;
33 children?: React.ReactNode;
34 initialEntries?: InitialEntry[];
35 initialIndex?: number;
36}
37/**
38 * A <Router> that stores all entries in memory.
39 *
40 * @see https://reactrouter.com/docs/en/v6/api#memoryrouter
41 */
42export declare function MemoryRouter({ basename, children, initialEntries, initialIndex }: MemoryRouterProps): React.ReactElement;
43export interface NavigateProps {
44 to: To;
45 replace?: boolean;
46 state?: any;
47}
48/**
49 * Changes the current location.
50 *
51 * Note: This API is mostly useful in React.Component subclasses that are not
52 * able to use hooks. In functional components, we recommend you use the
53 * `useNavigate` hook instead.
54 *
55 * @see https://reactrouter.com/docs/en/v6/api#navigate
56 */
57export declare function Navigate({ to, replace, state }: NavigateProps): null;
58export interface OutletProps {
59 context?: unknown;
60}
61/**
62 * Renders the child route's element, if there is one.
63 *
64 * @see https://reactrouter.com/docs/en/v6/api#outlet
65 */
66export declare function Outlet(props: OutletProps): React.ReactElement | null;
67export interface RouteProps {
68 caseSensitive?: boolean;
69 children?: React.ReactNode;
70 element?: React.ReactNode | null;
71 index?: boolean;
72 path?: string;
73}
74export interface PathRouteProps {
75 caseSensitive?: boolean;
76 children?: React.ReactNode;
77 element?: React.ReactNode | null;
78 index?: false;
79 path: string;
80}
81export interface LayoutRouteProps {
82 children?: React.ReactNode;
83 element?: React.ReactNode | null;
84}
85export interface IndexRouteProps {
86 element?: React.ReactNode | null;
87 index: true;
88}
89/**
90 * Declares an element that should be rendered at a certain URL path.
91 *
92 * @see https://reactrouter.com/docs/en/v6/api#route
93 */
94export declare function Route(_props: PathRouteProps | LayoutRouteProps | IndexRouteProps): React.ReactElement | null;
95export interface RouterProps {
96 basename?: string;
97 children?: React.ReactNode;
98 location: Partial<Location> | string;
99 navigationType?: NavigationType;
100 navigator: Navigator;
101 static?: boolean;
102}
103/**
104 * Provides location context for the rest of the app.
105 *
106 * Note: You usually won't render a <Router> directly. Instead, you'll render a
107 * router that is more specific to your environment such as a <BrowserRouter>
108 * in web browsers or a <StaticRouter> for server rendering.
109 *
110 * @see https://reactrouter.com/docs/en/v6/api#router
111 */
112export declare function Router({ basename: basenameProp, children, location: locationProp, navigationType, navigator, static: staticProp }: RouterProps): React.ReactElement | null;
113export interface RoutesProps {
114 children?: React.ReactNode;
115 location?: Partial<Location> | string;
116}
117/**
118 * A container for a nested tree of <Route> elements that renders the branch
119 * that best matches the current location.
120 *
121 * @see https://reactrouter.com/docs/en/v6/api#routes
122 */
123export declare function Routes({ children, location }: RoutesProps): React.ReactElement | null;
124/**
125 * Returns the full href for the given "to" value. This is useful for building
126 * custom links that are also accessible and preserve right-click behavior.
127 *
128 * @see https://reactrouter.com/docs/en/v6/api#usehref
129 */
130export declare function useHref(to: To): string;
131/**
132 * Returns true if this component is a descendant of a <Router>.
133 *
134 * @see https://reactrouter.com/docs/en/v6/api#useinroutercontext
135 */
136export declare function useInRouterContext(): boolean;
137/**
138 * Returns the current location object, which represents the current URL in web
139 * browsers.
140 *
141 * Note: If you're using this it may mean you're doing some of your own
142 * "routing" in your app, and we'd like to know what your use case is. We may
143 * be able to provide something higher-level to better suit your needs.
144 *
145 * @see https://reactrouter.com/docs/en/v6/api#uselocation
146 */
147export declare function useLocation(): Location;
148declare type ParamParseFailed = {
149 failed: true;
150};
151declare type ParamParseSegment<Segment extends string> = Segment extends `${infer LeftSegment}/${infer RightSegment}` ? ParamParseSegment<LeftSegment> extends infer LeftResult ? ParamParseSegment<RightSegment> extends infer RightResult ? LeftResult extends string ? RightResult extends string ? LeftResult | RightResult : LeftResult : RightResult extends string ? RightResult : ParamParseFailed : ParamParseFailed : ParamParseSegment<RightSegment> extends infer RightResult ? RightResult extends string ? RightResult : ParamParseFailed : ParamParseFailed : Segment extends `:${infer Remaining}` ? Remaining : ParamParseFailed;
152declare type ParamParseKey<Segment extends string> = ParamParseSegment<Segment> extends string ? ParamParseSegment<Segment> : string;
153/**
154 * Returns the current navigation action which describes how the router came to
155 * the current location, either by a pop, push, or replace on the history stack.
156 *
157 * @see https://reactrouter.com/docs/en/v6/api#usenavigationtype
158 */
159export declare function useNavigationType(): NavigationType;
160/**
161 * Returns true if the URL for the given "to" value matches the current URL.
162 * This is useful for components that need to know "active" state, e.g.
163 * <NavLink>.
164 *
165 * @see https://reactrouter.com/docs/en/v6/api#usematch
166 */
167export declare function useMatch<ParamKey extends ParamParseKey<Path>, Path extends string>(pattern: PathPattern<Path> | Path): PathMatch<ParamKey> | null;
168/**
169 * The interface for the navigate() function returned from useNavigate().
170 */
171export interface NavigateFunction {
172 (to: To, options?: NavigateOptions): void;
173 (delta: number): void;
174}
175export interface NavigateOptions {
176 replace?: boolean;
177 state?: any;
178}
179/**
180 * Returns an imperative method for changing the location. Used by <Link>s, but
181 * may also be used by other elements to change the location.
182 *
183 * @see https://reactrouter.com/docs/en/v6/api#usenavigate
184 */
185export declare function useNavigate(): NavigateFunction;
186/**
187 * Returns the context (if provided) for the child route at this level of the route
188 * hierarchy.
189 * @see https://reactrouter.com/docs/en/v6/api#useoutletcontext
190 */
191export declare function useOutletContext<Context = unknown>(): Context;
192/**
193 * Returns the element for the child route at this level of the route
194 * hierarchy. Used internally by <Outlet> to render child routes.
195 *
196 * @see https://reactrouter.com/docs/en/v6/api#useoutlet
197 */
198export declare function useOutlet(context?: unknown): React.ReactElement | null;
199/**
200 * Returns an object of key/value pairs of the dynamic params from the current
201 * URL that were matched by the route path.
202 *
203 * @see https://reactrouter.com/docs/en/v6/api#useparams
204 */
205export declare function useParams<ParamsOrKey extends string | Record<string, string | undefined> = string>(): Readonly<[
206 ParamsOrKey
207] extends [string] ? Params<ParamsOrKey> : Partial<ParamsOrKey>>;
208/**
209 * Resolves the pathname of the given `to` value against the current location.
210 *
211 * @see https://reactrouter.com/docs/en/v6/api#useresolvedpath
212 */
213export declare function useResolvedPath(to: To): Path;
214/**
215 * Returns the element of the route that matched the current location, prepared
216 * with the correct context to render the remainder of the route tree. Route
217 * elements in the tree must render an <Outlet> to render their child route's
218 * element.
219 *
220 * @see https://reactrouter.com/docs/en/v6/api#useroutes
221 */
222export declare function useRoutes(routes: RouteObject[], locationArg?: Partial<Location> | string): React.ReactElement | null;
223/**
224 * Creates a route config from a React "children" object, which is usually
225 * either a `<Route>` element or an array of them. Used internally by
226 * `<Routes>` to create a route config from its children.
227 *
228 * @see https://reactrouter.com/docs/en/v6/api#createroutesfromchildren
229 */
230export declare function createRoutesFromChildren(children: React.ReactNode): RouteObject[];
231/**
232 * The parameters that were parsed from the URL path.
233 */
234export declare type Params<Key extends string = string> = {
235 readonly [key in Key]: string | undefined;
236};
237/**
238 * A route object represents a logical route, with (optionally) its child
239 * routes organized in a tree-like structure.
240 */
241export interface RouteObject {
242 caseSensitive?: boolean;
243 children?: RouteObject[];
244 element?: React.ReactNode;
245 index?: boolean;
246 path?: string;
247}
248/**
249 * Returns a path with params interpolated.
250 *
251 * @see https://reactrouter.com/docs/en/v6/api#generatepath
252 */
253export declare function generatePath(path: string, params?: Params): string;
254/**
255 * A RouteMatch contains info about how a route matched a URL.
256 */
257export interface RouteMatch<ParamKey extends string = string> {
258 /**
259 * The names and values of dynamic parameters in the URL.
260 */
261 params: Params<ParamKey>;
262 /**
263 * The portion of the URL pathname that was matched.
264 */
265 pathname: string;
266 /**
267 * The portion of the URL pathname that was matched before child routes.
268 */
269 pathnameBase: string;
270 /**
271 * The route object that was used to match.
272 */
273 route: RouteObject;
274}
275/**
276 * Matches the given routes to a location and returns the match data.
277 *
278 * @see https://reactrouter.com/docs/en/v6/api#matchroutes
279 */
280export declare function matchRoutes(routes: RouteObject[], locationArg: Partial<Location> | string, basename?: string): RouteMatch[] | null;
281/**
282 * Renders the result of `matchRoutes()` into a React element.
283 */
284export declare function renderMatches(matches: RouteMatch[] | null): React.ReactElement | null;
285/**
286 * A PathPattern is used to match on some portion of a URL pathname.
287 */
288export interface PathPattern<Path extends string = string> {
289 /**
290 * A string to match against a URL pathname. May contain `:id`-style segments
291 * to indicate placeholders for dynamic parameters. May also end with `/*` to
292 * indicate matching the rest of the URL pathname.
293 */
294 path: Path;
295 /**
296 * Should be `true` if the static portions of the `path` should be matched in
297 * the same case.
298 */
299 caseSensitive?: boolean;
300 /**
301 * Should be `true` if this pattern should match the entire URL pathname.
302 */
303 end?: boolean;
304}
305/**
306 * A PathMatch contains info about how a PathPattern matched on a URL pathname.
307 */
308export interface PathMatch<ParamKey extends string = string> {
309 /**
310 * The names and values of dynamic parameters in the URL.
311 */
312 params: Params<ParamKey>;
313 /**
314 * The portion of the URL pathname that was matched.
315 */
316 pathname: string;
317 /**
318 * The portion of the URL pathname that was matched before child routes.
319 */
320 pathnameBase: string;
321 /**
322 * The pattern that was used to match.
323 */
324 pattern: PathPattern;
325}
326/**
327 * Performs pattern matching on a URL pathname and returns information about
328 * the match.
329 *
330 * @see https://reactrouter.com/docs/en/v6/api#matchpath
331 */
332export declare function matchPath<ParamKey extends ParamParseKey<Path>, Path extends string>(pattern: PathPattern<Path> | Path, pathname: string): PathMatch<ParamKey> | null;
333/**
334 * Returns a resolved path object relative to the given pathname.
335 *
336 * @see https://reactrouter.com/docs/en/v6/api#resolvepath
337 */
338export declare function resolvePath(to: To, fromPathname?: string): Path;
339/** @internal */
340export { NavigationContext as UNSAFE_NavigationContext, LocationContext as UNSAFE_LocationContext, RouteContext as UNSAFE_RouteContext };