Skip to content

Commit 9854ca2

Browse files
ryanflorenceryanflorence
committed
docs: moved API into their own docs :D
1 parent 4172a9d commit 9854ca2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+1853
-1519
lines changed

‎docs/api.md

Lines changed: 0 additions & 1488 deletions
This file was deleted.

‎docs/components/index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Components
3+
order: 4
4+
---

‎docs/components/link-native.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: Link (React Native)
3+
---
4+
5+
# `<Link>` (React Native)
6+
7+
> **Note:**
8+
>
9+
> This is the React Native version of `<Link>`. For the web version,
10+
> [go here][link].
11+
12+
<details>
13+
<summary>Type declaration</summary>
14+
15+
```tsx
16+
declare function Link(props: LinkProps): React.ReactElement;
17+
18+
interface LinkProps extends TouchableHighlightProps {
19+
children?: React.ReactNode;
20+
onPress?(event: GestureResponderEvent): void;
21+
replace?: boolean;
22+
state?: any;
23+
to: To;
24+
}
25+
```
26+
27+
</details>
28+
29+
A `<Link>` is an element that lets the user navigate to another view by tapping it, similar to how `<a>` elements work in a web app. In `react-router-native`, a `<Link>` renders a `TouchableHighlight`. To override default styling and behaviour, please refer to the [Props reference for `TouchableHighlight`](https://reactnative.dev/docs/touchablehighlight#props).
30+
31+
```tsx
32+
import * as React from "react";
33+
import { View, Text } from "react-native";
34+
import { Link } from "react-router-native";
35+
36+
function Home() {
37+
return (
38+
<View>
39+
<Text>Welcome!</Text>
40+
<Link to="/profile">Visit your profile</Link>
41+
</View>
42+
);
43+
}
44+
```
45+
46+
[link]: ./link-native

‎docs/components/link.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Link
3+
---
4+
5+
# `<Link>`
6+
7+
> **Note:**
8+
>
9+
> This is the web version of `<Link>`. For the React Native version,
10+
> [go here][link-native].
11+
12+
<details>
13+
<summary>Type declaration</summary>
14+
15+
```tsx
16+
declare function Link(props: LinkProps): React.ReactElement;
17+
18+
interface LinkProps
19+
extends Omit<
20+
React.AnchorHTMLAttributes<HTMLAnchorElement>,
21+
"href"
22+
> {
23+
replace?: boolean;
24+
state?: any;
25+
to: To;
26+
reloadDocument?: boolean;
27+
}
28+
29+
type To = Partial<Location> | string;
30+
```
31+
32+
</details>
33+
34+
A `<Link>` is an element that lets the user navigate to another page by clicking or tapping on it. In `react-router-dom`, a `<Link>` renders an accessible `<a>` element with a real `href` that points to the resource it's linking to. This means that things like right-clicking a `<Link>` work as you'd expect. You can use `<Link reloadDocument>` to skip client side routing and let the browser handle the transition normally (as if it were an `<a href>`).
35+
36+
```tsx
37+
import * as React from "react";
38+
import { Link } from "react-router-dom";
39+
40+
function UsersIndexPage({ users }) {
41+
return (
42+
<div>
43+
<h1>Users</h1>
44+
<ul>
45+
{users.map((user) => (
46+
<li key={user.id}>
47+
<Link to={user.id}>{user.name}</Link>
48+
</li>
49+
))}
50+
</ul>
51+
</div>
52+
);
53+
}
54+
```
55+
56+
A relative `<Link to>` value (that does not begin with `/`) resolves relative to the parent route, which means that it builds upon the URL path that was matched by the route that rendered that `<Link>`. It may contain `..` to link to routes further up the hierarchy. In these cases, `..` works exactly like the command-line `cd` function; each `..` removes one segment of the parent path.
57+
58+
> **Note:**
59+
>
60+
> `<Link to>` with a `..` behaves differently from a normal `<a href>` when the
61+
> current URL ends with `/`. `<Link to>` ignores the trailing slash, and removes
62+
> one URL segment for each `..`. But an `<a href>` value handles `..`
63+
> differently when the current URL ends with `/` vs when it does not.
64+
65+
[link-native]: ./link-native

‎docs/components/nav-link.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: NavLink
3+
---
4+
5+
# `<NavLink>`
6+
7+
<details>
8+
<summary>Type declaration</summary>
9+
10+
```tsx
11+
declare function NavLink(
12+
props: NavLinkProps
13+
): React.ReactElement;
14+
15+
interface NavLinkProps
16+
extends Omit<
17+
LinkProps,
18+
"className" | "style" | "children"
19+
> {
20+
caseSensitive?: boolean;
21+
children?:
22+
| React.ReactNode
23+
| ((props: { isActive: boolean }) => React.ReactNode);
24+
className?:
25+
| string
26+
| ((props: {
27+
isActive: boolean;
28+
}) => string | undefined);
29+
end?: boolean;
30+
style?:
31+
| React.CSSProperties
32+
| ((props: {
33+
isActive: boolean;
34+
}) => React.CSSProperties);
35+
}
36+
```
37+
38+
</details>
39+
40+
A `<NavLink>` is a special kind of [`<Link>`][link] that knows whether or not it is "active". This is useful when building a navigation menu such as a breadcrumb or a set of tabs where you'd like to show which of them is currently selected. It also provides useful context for assistive technology like screen readers.
41+
42+
By default, an `active` class is added to a `<NavLink>` component when it is active. This provides the same simple styling mechanism for most users who are upgrading from v5. One difference as of `v6.0.0-beta.3` is that `activeClassName` and `activeStyle` have been removed from `NavLinkProps`. Instead, you can pass a function to either `style` or `className` that will allow you to customize the inline styling or the class string based on the component's active state. You can also pass a function as children to customize the content of the `<NavLink>` component based on their active state, specially useful to change styles on internal elements.
43+
44+
```tsx
45+
import * as React from "react";
46+
import { NavLink } from "react-router-dom";
47+
48+
function NavList() {
49+
// This styling will be applied to a <NavLink> when the
50+
// route that it links to is currently selected.
51+
let activeStyle = {
52+
textDecoration: "underline",
53+
};
54+
55+
let activeClassName = "underline";
56+
57+
return (
58+
<nav>
59+
<ul>
60+
<li>
61+
<NavLink
62+
to="messages"
63+
style={({ isActive }) =>
64+
isActive ? activeStyle : undefined
65+
}
66+
>
67+
Messages
68+
</NavLink>
69+
</li>
70+
<li>
71+
<NavLink
72+
to="tasks"
73+
className={({ isActive }) =>
74+
isActive ? activeClassName : undefined
75+
}
76+
>
77+
Tasks
78+
</NavLink>
79+
</li>
80+
<li>
81+
<NavLink to="tasks">
82+
{({ isActive }) => (
83+
<span
84+
className={
85+
isActive ? activeClassName : undefined
86+
}
87+
>
88+
Tasks
89+
</span>
90+
)}
91+
</NavLink>
92+
</li>
93+
</ul>
94+
</nav>
95+
);
96+
}
97+
```
98+
99+
If you prefer the v5 API, you can create your own `<NavLink />` as a wrapper component:
100+
101+
```tsx
102+
import * as React from "react";
103+
import { NavLink as BaseNavLink } from "react-router-dom";
104+
105+
const NavLink = React.forwardRef(
106+
({ activeClassName, activeStyle, ...props }, ref) => {
107+
return (
108+
<BaseNavLink
109+
ref={ref}
110+
{...props}
111+
className={({ isActive }) =>
112+
[
113+
props.className,
114+
isActive ? activeClassName : null,
115+
]
116+
.filter(Boolean)
117+
.join(" ")
118+
}
119+
style={({ isActive }) => ({
120+
...props.style,
121+
...(isActive ? activeStyle : null),
122+
})}
123+
/>
124+
);
125+
}
126+
);
127+
```
128+
129+
If the `end` prop is used, it will ensure this component isn't matched as "active" when its descendant paths are matched. For example, to render a link that is only active at the website root and not any other URLs, you can use:
130+
131+
```tsx
132+
<NavLink to="/" end>
133+
Home
134+
</NavLink>
135+
```
136+
137+
[link]: ./link

‎docs/components/navigate.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Navigate
3+
---
4+
5+
# `<Navigate>`
6+
7+
<details>
8+
<summary>Type declaration</summary>
9+
10+
```tsx
11+
declare function Navigate(props: NavigateProps): null;
12+
13+
interface NavigateProps {
14+
to: To;
15+
replace?: boolean;
16+
state?: any;
17+
}
18+
```
19+
20+
</details>
21+
22+
A `<Navigate>` element changes the current location when it is rendered. It's a component wrapper around [`useNavigate`][use-navigate], and accepts all the same arguments as props.
23+
24+
> **Note:**
25+
>
26+
> Having a component-based version of the `useNavigate` hook makes it easier to
27+
> use this feature in a [`React.Component`](https://reactjs.org/docs/react-component.html)
28+
> subclass where hooks are not able to be used.
29+
30+
```tsx
31+
import * as React from "react";
32+
import { Navigate } from "react-router-dom";
33+
34+
class LoginForm extends React.Component {
35+
state = { user: null, error: null };
36+
37+
async handleSubmit(event) {
38+
event.preventDefault();
39+
try {
40+
let user = await login(event.target);
41+
this.setState({ user });
42+
} catch (error) {
43+
this.setState({ error });
44+
}
45+
}
46+
47+
render() {
48+
let { user, error } = this.state;
49+
return (
50+
<div>
51+
{error && <p>{error.message}</p>}
52+
{user && (
53+
<Navigate to="/dashboard" replace={true} />
54+
)}
55+
<form
56+
onSubmit={(event) => this.handleSubmit(event)}
57+
>
58+
<input type="text" name="username" />
59+
<input type="password" name="password" />
60+
</form>
61+
</div>
62+
);
63+
}
64+
}
65+
```
66+
67+
[use-navigate]: ../hooks/use-navigate

‎docs/components/outlet.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Outlet
3+
---
4+
5+
# `<Outlet>`
6+
7+
<details>
8+
<summary>Type declaration</summary>
9+
10+
```tsx
11+
interface OutletProps {
12+
context?: unknown;
13+
}
14+
declare function Outlet(
15+
props: OutletProps
16+
): React.ReactElement | null;
17+
```
18+
19+
</details>
20+
21+
An `<Outlet>` should be used in parent route elements to render their child route elements. This allows nested UI to show up when child routes are rendered. If the parent route matched exactly, it will render a child index route or nothing if there is no index route.
22+
23+
```tsx
24+
function Dashboard() {
25+
return (
26+
<div>
27+
<h1>Dashboard</h1>
28+
29+
{/* This element will render either <DashboardMessages> when the URL is
30+
"/messages", <DashboardTasks> at "/tasks", or null if it is "/"
31+
*/}
32+
<Outlet />
33+
</div>
34+
);
35+
}
36+
37+
function App() {
38+
return (
39+
<Routes>
40+
<Route path="/" element={<Dashboard />}>
41+
<Route
42+
path="messages"
43+
element={<DashboardMessages />}
44+
/>
45+
<Route path="tasks" element={<DashboardTasks />} />
46+
</Route>
47+
</Routes>
48+
);
49+
}
50+
```

0 commit comments

Comments
 (0)