| 1 | # Link and NavLink
|
| 2 |
|
| 3 | Auxiliary wrappers around [React Router](https://github.com/ReactTraining/react-router)'s
|
| 4 | `<Link>` and `<NavLink>` components; they help to handle external and internal
|
| 5 | links in a single uniform manner.
|
| 6 |
|
| 7 | [Examples](#examples)
|
| 8 |
|
| 9 | **Why?** — We use React Router to handle routing of our applications.
|
| 10 | React Router's `<Link>` and `<NavLink>` components work only with the
|
| 11 | application's internal links; to properly handle external links it is necessary
|
| 12 | to render them as `<a>` HTML elements. Our custom wrappers hide the difference
|
| 13 | between internal and extrenal links, allowing to handle them via the same
|
| 14 | interface provided by React Router, and extended with a few extra properties for
|
| 15 | advance behaviours. It is convenient both when the rendered links come from a
|
| 16 | visitor / database (thus you don't have to check yourself whether they are
|
| 17 | external or internal), and also when you have to frequently change the actual
|
| 18 | link addresses, as it often happens during active development / prototyping.
|
| 19 |
|
| 20 | Our `<Link>` and `<NavLink>` are rendered as simple `<a>` elements when:
|
| 21 | 1. The link is absolute, i.e. starts with `http://` or `https://`;
|
| 22 | 2. The link points to an anchor, i.e. starts with `#` symbol;
|
| 23 | 3. The link should be opened in a new tab (`openNewTab` property);
|
| 24 | 4. Explicitly opted by the `enforceA` property;
|
| 25 |
|
| 26 | Otherwise, `<Link>` and `<NavLink>` are rendered as the corresponding React
|
| 27 | Router's components. Additionally in this case, the links to the current page,
|
| 28 | when clicked, scroll the page to the top.
|
| 29 |
|
| 30 | Both `<Link>` and `<NavLink>` support all properties of the underlying React
|
| 31 | Router's components, along with some additional props:
|
| 32 |
|
| 33 | ### Link properties
|
| 34 | - **`children`** — *Node* — Optional. Child ReactJS node to render
|
| 35 | inside the link;
|
| 36 | - **`className`** — *String* — Optional. Class(es) to apply to the
|
| 37 | rendered link;
|
| 38 | - **`enforceA`** — *Boolean* — Optional. If *true* enforces
|
| 39 | rendering of the link as a simple `<a>` element;
|
| 40 | - **`onClick`** — *Function* — Optional. An event handler to trigger
|
| 41 | on click;
|
| 42 | - **`onMouseDown`** — *Function* — Optional. An event handler to
|
| 43 | trigger on MouseDown event;
|
| 44 | - **`openNewTab`** — *Boolean* — Optional. If *true* the link will
|
| 45 | be opened in a new tab;
|
| 46 | - **`replace`** — *Boolean* — Optional. When *true*, clicking the
|
| 47 | link will replace the current entry in the history stack instead of adding a new
|
| 48 | one;
|
| 49 | - **`to`** — *String* — Optional. Link URL. Defaults to empty
|
| 50 | string.
|
| 51 |
|
| 52 | ### NavLink properties
|
| 53 | `<NavLink>` supports all properties of `<Link>`, listed above, and the following
|
| 54 | additional ones, coming from React Router:
|
| 55 | - **`activeClassName`** — *String* — Optional. Class(es) to apply to
|
| 56 | the rendered link when it is active;
|
| 57 | - **`activeStyle`** — *String* — Optional. Styles to apply to the
|
| 58 | rendered link when it is active;
|
| 59 | - **`exact`** — *Boolean* — Optional. When *true*, the active
|
| 60 | class/style will only be applied if the location is matched exactly;
|
| 61 | - **`isActive`** — *Function* — Optional. A function to add extra
|
| 62 | logic for determining whether the link is active. This should be used if you
|
| 63 | want to do more than verify that the link’s pathname matches the current URL’s
|
| 64 | pathname;
|
| 65 | - **`location`** — *Object* — Optional. The `isActive` compares the
|
| 66 | current history location (usually the current browser URL). To compare to a
|
| 67 | different location, a `location` can be passed.
|
| 68 | - **`strict`** — *Boolean* — Optional. When `true`, the trailing
|
| 69 | slash on a location’s pathname will be taken into consideration when determining
|
| 70 | if the location matches the current URL. See the <Route strict> documentation
|
| 71 | for more information.
|
| 72 |
|
| 73 | ### <a name="examples">Examples</a>
|
| 74 |
|
| 75 | Minimal `<Link>` example:
|
| 76 | ```js
|
| 77 | import { Link } from 'topcoder-react-utils';
|
| 78 |
|
| 79 | export default function LinksExample() {
|
| 80 | return <Link to="some/url">Link to Some URL</a>;
|
| 81 | }
|
| 82 | ```
|