Repository navigation
Link: mark the link to the current page (aria-current, data-active) #676
Description
Summary
Link renders a plain <a> with no sign that it points to the current page. Every navigation menu (a header, a sidebar, tabs) has to compare useRouter().path with each link's href by hand. Those hand-written checks usually style the active link but forget aria-current="page", so screen readers aren't told which link is the current page.
Example
What an app writes today:
import { Link, useRouter } from '@void/react';
// The section's home link only matches itself; the others also match their nested pages.
function isActive(path: string, href: string, home: string) {
return path === href || (href !== home && path.startsWith(`${href}/`));
}
function Sidebar({ links, home }: { links: { href: string; label: string }[]; home: string }) {
const { path } = useRouter();
return links.map((link) => {
const active = isActive(path, link.href, home);
return (
<Link
key={link.href}
href={link.href}
data-active={active || undefined}
aria-current={active ? 'page' : undefined}
>
{link.label}
</Link>
);
});
}What it could be:
<Link href="/admin">Overview</Link>
<Link href="/admin/users" activeMatch="prefix">Users</Link>Proposal
aria-current="page"when the link's path is the current path. It's semantically "this is the current page", so exact match only.data-activeon the same link, for styling with[data-active]or Tailwind'sdata-active:. Unlike a class, it doesn't collide with the app's ownclassName.- An opt-in for nested pages, for example
activeMatch="prefix", so/admin/usersstays highlighted on/admin/users/42. It matches whole path segments, so/admin/usersdoesn't match/admin/users-archive. - Ignore the query and hash when matching, so
/inbox?page=2still marks/inbox.
The names are only suggestions. The router already holds the current path in every adapter, so this should look the same in React, Vue, Svelte and Solid. #672, which moves the shared Link logic into void/pages-client, looks like the natural place for the matching.
Prior art
- React Router:
NavLinksetsaria-current="page"and anactiveclass, and takesendto choose between exact and nested matching. - TanStack Router:
Linksetsaria-current="page"anddata-status="active", and takesactiveOptions: { exact, includeSearch }andactiveProps. - Vue Router:
RouterLinkaddsrouter-link-activefor nested matches, androuter-link-exact-activeplusaria-current="page"for exact ones. - Nuxt:
NuxtLinktakesactiveClassandexactActiveClass.
Environment
void1.5.0@void/react1.5.0
Metadata
Metadata
Assignees
Labels
No labels
Type
Fields
Priority
None yet
Activity
yangshun commentedon Nov 3, 2026
Proposal: active state for
LinkLinkmarks the link to the current page witharia-current="page"anddata-void-active. It matches exactly by default, andactiveMatch="prefix"keeps a link active on nested pages. The behavior is the same in React, Vue, Svelte and Solid.Key decisions
/docslink in a footer on every docs page. An exact default keeps both attributes in agreement unless a link opts in.aria-currenton exact matches only. It means "this page", so a nested page shouldn't get it. Nested pages that want this can specifyactiveMatch="prefix".data-void-activeattribute as a styling hook. It followsdata-void-form-error, the existing presence-only attribute thatFormrenders in all four adapters. We don't use a class or call it justdata-active, the-voidprefix avoids colliding with the app's own attributes, and a class would need merging four different ways.API
One new prop:
Two attributes that
Linkrenders:data-void-activeactiveMatch="prefix"aria-current="page"activeMatchis set toThese attributes can be used for styling.
An
aria-currentordata-void-activepassed toLinkoverrides the computed value.Matching rules
exact: the same pathname.prefix: the same pathname, or one that continues with/after the link's path. Only whole segments match, and/only matches itself.<button>and are never active.Examples
✓ = rendered, — = not rendered.
Exact matching (default)
Linkdata-void-activearia-current/admin/usershref="/admin/users""page"/admin/users/42href="/admin/users"Nested pages (
activeMatch="prefix")Linkdata-void-activearia-current/admin/usershref="/admin/users""page"aria-current/admin/users/42href="/admin/users"/admin/users-archivehref="/admin/users"/admin/usershref="/"/only matches itselfQuery and hash
Linkdata-void-activearia-current/inbox?page=2href="/inbox""page"/settings?tab=billinghref="/settings?tab=profile""page"/docshref="/docs#install""page"Edge cases
Linkdata-void-activearia-current/href="https://example.com/"/logouthref="/logout" method="post"<button>/checkout/shippinghref="/checkout/shipping" aria-current="step""step"Open questions
href="/admin/"match/admin? I think it should follow how Void's router treats the two URLs.href="/Admin"match/admin? I think yes, since URLs are generally case-insensitive and most other routers do that.Not in this proposal
activeClass/activeProps,({ isActive })children, a public matching hook, options for matching the query or hash, anddata-pending. Each could be added later without a breaking change.cpojer commentedon Nov 3, 2026
I like the proposal. Make sure to add docs for it too so agents discover it.
feat(pages): mark the Link to the current page (#687)