ButtonLink

A real <a> that looks like a Button. It wraps an anchor with TanStack Router’s createLink, so it shares Button’s variants and sizes but navigates instead of firing an onClick.

Reach for ButtonLink whenever a button-styled control should change the route — a “View order” call to action, an “Add store” header action, a back link. Use Button for actions that don’t navigate (submit, open a dialog, mutate). Because it renders an anchor, it gets browser link behavior for free: right-click to open in a new tab, middle-click, copy address.

Default

Pass to, params, and search directly — they’re fully typed against the consumer’s route tree. Always route dynamic segments through params (e.g. to="/orgs/$orgSlug" params={{ orgSlug }}) rather than interpolating into the path string; interpolation skips type checking and silently breaks when a route changes.

import {
  createMemoryHistory,
  createRootRoute,
  createRoute,
  createRouter,
  RouterProvider,
} from "@tanstack/react-router";
import { ButtonLink, HStack } from "@vesyl/ui-next";

const orgSlug = "acme";

function ButtonLinkExample() {
  return (
    <HStack justify="center">
      <ButtonLink to="/orgs/$orgSlug/settings" params={{ orgSlug }}>
        Open settings
      </ButtonLink>
    </HStack>
  );
}

const rootRoute = createRootRoute({ component: ButtonLinkExample });
const settingsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/orgs/$orgSlug/settings",
});
const routeTree = rootRoute.addChildren([settingsRoute]);

const router = createRouter({
  routeTree,
  history: createMemoryHistory({ initialEntries: ["/"] }),
});

declare module "@tanstack/react-router" {
  interface Register {
    router: typeof router;
  }
}

export default function ButtonLinkDefault() {
  return <RouterProvider router={router} />;
}

Variants

variant maps 1:1 to Button — default, secondary, outline, ghost, destructive, and link. Plain string hrefs work too when you’re linking outside the router (external URLs, anchors).

import {
  RouterProvider,
  createMemoryHistory,
  createRootRoute,
  createRouter,
} from "@tanstack/react-router";
import { ButtonLink, HStack } from "@vesyl/ui-next";

function ButtonLinkVariantsExample() {
  return (
    <HStack gap={3} justify="center" className="flex-wrap">
      <ButtonLink href="/orders" variant="default">
        Default
      </ButtonLink>
      <ButtonLink href="/orders" variant="secondary">
        Secondary
      </ButtonLink>
      <ButtonLink href="/orders" variant="outline">
        Outline
      </ButtonLink>
      <ButtonLink href="/orders" variant="ghost">
        Ghost
      </ButtonLink>
      <ButtonLink href="/orders" variant="destructive">
        Destructive
      </ButtonLink>
      <ButtonLink href="/orders" variant="link">
        Link
      </ButtonLink>
    </HStack>
  );
}

const rootRoute = createRootRoute({ component: ButtonLinkVariantsExample });
const router = createRouter({
  routeTree: rootRoute,
  history: createMemoryHistory({ initialEntries: ["/"] }),
});

export default function ButtonLinkVariants() {
  return <RouterProvider router={router} />;
}

Sizes

size matches Button: md (default), xs, sm, and lg control height, padding, and text size.

import {
  RouterProvider,
  createMemoryHistory,
  createRootRoute,
  createRouter,
} from "@tanstack/react-router";
import { ButtonLink, HStack } from "@vesyl/ui-next";

function ButtonLinkSizesExample() {
  return (
    <HStack gap={3} justify="center" align="end" className="flex-wrap">
      <ButtonLink href="/orders" size="xs">
        Extra Small
      </ButtonLink>
      <ButtonLink href="/orders" size="sm">
        Small
      </ButtonLink>
      <ButtonLink href="/orders" size="md">
        Medium
      </ButtonLink>
      <ButtonLink href="/orders" size="lg">
        Large
      </ButtonLink>
    </HStack>
  );
}

const rootRoute = createRootRoute({ component: ButtonLinkSizesExample });
const router = createRouter({
  routeTree: rootRoute,
  history: createMemoryHistory({ initialEntries: ["/"] }),
});

export default function ButtonLinkSizes() {
  return <RouterProvider router={router} />;
}

With icons

Mark a leading or trailing lucide icon with data-icon="inline-start" / data-icon="inline-end" so it picks up the correct gap and edge padding — the same convention as Button.

import {
  RouterProvider,
  createMemoryHistory,
  createRootRoute,
  createRouter,
} from "@tanstack/react-router";
import { ButtonLink, HStack } from "@vesyl/ui-next";
import { ArrowRight, Plus } from "lucide-react";

function ButtonLinkIconsExample() {
  return (
    <HStack gap={3} justify="center" className="flex-wrap">
      <ButtonLink href="/orders/new" variant="outline">
        Add order
        <Plus data-icon="inline-end" />
      </ButtonLink>
      <ButtonLink href="/orders">
        View all orders
        <ArrowRight data-icon="inline-end" />
      </ButtonLink>
    </HStack>
  );
}

const rootRoute = createRootRoute({ component: ButtonLinkIconsExample });
const router = createRouter({
  routeTree: rootRoute,
  history: createMemoryHistory({ initialEntries: ["/"] }),
});

export default function ButtonLinkIcons() {
  return <RouterProvider router={router} />;
}

Reference

ButtonLink

An <a> styled with buttonVariants, wrapped in TanStack Router’s createLink. Accepts every Link prop (to, params, search, from, hash, replace, …) plus the variant props below, and any native <a> attribute such as href or target.

Prop	Type	Default	Description
`to`	route path	—	Typesafe destination route (preferred over `href`)
`params`	object	—	Values for dynamic segments in `to`
`search`	object	—	Query-string params, typed against the route
`href`	`string`	—	Native anchor target for external / non-router links
`variant`	`"default" \| "secondary" \| "outline" \| "ghost" \| "destructive" \| "link"`	`"default"`	Visual style; mirrors `Button`
`size`	`"md" \| "xs" \| "sm" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-lg"`	`"md"`	Height, padding, and text size; mirrors `Button`
`className`	`string`	—	Merged onto the anchor