Link options

Edit this page on GitHub

In SvelteKit, <a> elements (rather than framework-specific <Link> components) are used to navigate between the routes of your app. If the user clicks on a link whose href is 'owned' by the app (as opposed to, say, a link to an external site) then SvelteKit will navigate to the new page by importing its code and then calling any load functions it needs to fetch data.

You can customise the behaviour of links with data-sveltekit-* attributes. These can be applied to the <a> itself, or to a parent element.

data-sveltekit-preload-datapermalink

Before the browser registers that the user has clicked on a link, we can detect that they've hovered the mouse over it (on desktop) or that a touchstart or mousedown event has happened. In both cases, we can make an educated guess that a click event is coming.

SvelteKit can use this information to get a head start on importing the code and fetching the page's data, which can give us an extra couple of hundred milliseconds — the difference between a user interface that feels laggy and one that feels snappy.

We can control this behaviour with the data-sveltekit-preload-data attribute, which can have one of two values:

"hover" means that preloading will start if the mouse comes to a rest over a link
"tap" means that preloading will start as soon as a touchstart or mousedown event is registered

On mobile, links with "hover" will preload on touchstart.

The default project template has a data-sveltekit-preload-data="hover" attribute applied to the <body> element in src/app.html, meaning that every link is preloaded on hover by default:

<body data-sveltekit-preload-data="hover">
  <div style="display: contents">%sveltekit.body%</div>
</body>

Sometimes, calling load when the user hovers over a link might be undesirable, either because it's likely to result in false positives (a click needn't follow a hover) or because data is updating very quickly and a delay could mean staleness.

In these cases, you can specify the "tap" value, which causes SvelteKit to call load only when the user taps or clicks on a link:

<a data-sveltekit-preload-data="tap" href="/stonks">
  Get current stonk values
</a>

You can also programmatically invoke preloadData from $app/navigation.

Data will never be preloaded if the user has chosen reduced data usage, meaning navigator.connection.saveData is true.

data-sveltekit-preload-codepermalink

Even in cases where you don't want to preload data for a link, it can be beneficial to preload the code. The data-sveltekit-preload-code attribute works similarly to data-sveltekit-preload-data, except that it can take one of four values, in decreasing 'eagerness':

"page" means that all links on the page will be preloaded
"viewport" means that links will be preloaded once they enter the viewport
"hover" - as above, except that only code is preloaded
"tap" - as above, except that only code is preloaded

Note that viewport and page only apply to links that are present in the DOM immediately following navigation. This is to avoid performance pitfalls resulting from aggressively observing the DOM for changes.

Since preloading code is a prerequisite for preloading data, this attribute will only have an effect if it specifies a more eager value than any data-sveltekit-preload-data attribute that is present.

As with data-sveltekit-preload-data, this attribute will be ignored if the user has chosen reduced data usage.

data-sveltekit-reloadpermalink

Occasionally, we need to tell SvelteKit not to handle a link, but allow the browser to handle it. Adding a data-sveltekit-reload attribute to a link...

<a data-sveltekit-reload href="/path">Path</a>

...will cause a full-page navigation when the link is clicked.

Links with a rel="external" attribute will receive the same treatment. In addition, they will be ignored during prerendering.

data-sveltekit-noscrollpermalink

When navigating to internal links, SvelteKit mirrors the browser's default navigation behaviour: it will change the scroll position to 0,0 so that the user is at the very top left of the page (unless the link includes a #hash, in which case it will scroll to the element with a matching ID).

In certain cases, you may wish to disable this behaviour. Adding a data-sveltekit-noscroll attribute to a link...

<a href="path" data-sveltekit-noscroll>Path</a>

...will prevent scrolling after the link is clicked.

Disabling optionspermalink

To disable any of these options inside an element where they have been enabled, use the "off" value:

<div data-sveltekit-preload-data>
  <!-- these links will be preloaded -->  <a href="/a">a</a>
  <a href="/b">b</a>
  <a href="/c">c</a>

  <div data-sveltekit-preload-data="off">
    <!-- these links will NOT be preloaded -->    <a href="/d">d</a>
    <a href="/e">e</a>
    <a href="/f">f</a>
  </div>
</div>

To apply an attribute to an element conditionally, do this:

<div data-sveltekit-reload={shouldReload ? '' : 'off'}>

This works because in HTML, <element attribute> is equivalent to <element attribute="">

previous Errors

next Service workers

JavaScript TypeScript