From f5016dd3d5394ec90f3557630270444441b17685 Mon Sep 17 00:00:00 2001 From: Atila Fassina Date: Tue, 14 May 2024 14:04:17 +0200 Subject: [PATCH] Expand info on `` reference to include `` (#718) --- .../solid-router/reference/components/a.mdx | 30 +++++++++++++++++-- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/src/routes/solid-router/reference/components/a.mdx b/src/routes/solid-router/reference/components/a.mdx index 05bc25b3e..b0d1ef20e 100644 --- a/src/routes/solid-router/reference/components/a.mdx +++ b/src/routes/solid-router/reference/components/a.mdx @@ -2,11 +2,35 @@ title: A --- -Like the [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) tag but supports relative paths and active class styling (requires client side JavaScript). +Solid-Router exposes an `` component as a wrapper around the native [``](https://mdn.io/a) tag. + +`` supports relative and base paths. `` doesn't. But `` gets augmented +when JS is present via a top-level listener to the DOM, so you get the +soft-navigation experience nonetheless. + +The `` supports the [``](/solid-router/reference/components/router) base property (``) and prepend it to the received `href` automatically and the ``does not. +The same happens with relative paths passed to ``. The `` tag has an `active` class if its href matches the current location, and `inactive` otherwise. -**Note:** By default matching includes locations that are descendents (eg. href `/users` matches locations `/users` and `/users/123`), use the boolean `end` prop to prevent matching these. -This is particularly useful for links to the root route `/` which would match everything. +By default matching includes locations that are descendants (e.g.: href `/users` matches locations `/users` and `/users/123`). + + + Use the boolean `end` prop to prevent matching these. This is particularly + useful for links to the root route `/` which would match everything. + + +## Soft Navigation + +When JavaScript is present at the runtime, both components behave in a very similar fashion. +This is because Solid-Router adds a listener at the top level of the DOM and will augment the native `` tag to a more performant experience (with soft navigation). + + + +To prevent, both `` and `` tags from soft navigating when JavaScript is present, pass a `target="_self"` attribute. + + + +## Props Reference | prop | type | description | | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |