Link Group

The LinkGroup component renders an ordered collection of LinkItem entries using the Link component. It supports position-based variant assignment via an ordered slot system, flexible container semantics (div, ul, nav), and full delegation of per-item rendering, accessibility, and fallback behavior to Link.

npx shadcn@latest add @rokkit200-ui/link-group

Preview

Get StartedLearn MoreContact Us

Code

import { LinkGroup } from "@/registry/rokkit200-ui/components/link-group/link-group";
import type { LinkItem } from "@/registry/rokkit200-ui/components/link/link";

const items: LinkItem[] = [
    {
        id: "1",
        label: "Get Started",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "2",
        label: "Learn More",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "3",
        label: "Contact Us",
        destination: { type: "internal", href: "#" },
    },
];

export default function LinkGroupDefaultDemo() {
    return (
        <LinkGroup items={items} className="flex gap-2" linkClassName="w-1/3" />
    );
}

Usage

import { LinkGroup } from "@/rokkit200-ui/components/link-group/link-group";

<LinkGroup
    items={items}
    className="flex gap-2"
    linkClassName="w-1/3"
/>

Examples

Single Variant

When a single variant slot is provided, all items receive that variant.

Preview

Get StartedLearn MoreContact Us

Code

import { LinkGroup } from "@/registry/rokkit200-ui/components/link-group/link-group";
import type { LinkItem } from "@/registry/rokkit200-ui/components/link/link";

const items: LinkItem[] = [
    {
        id: "1",
        label: "Get Started",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "2",
        label: "Learn More",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "3",
        label: "Contact Us",
        destination: { type: "internal", href: "#" },
    },
];

export default function LinkGroupSingleVariantDemo() {
    return (
        <LinkGroup
            items={items}
            variantSlots={["secondary"]}
            className="flex gap-2"
            linkClassName="w-1/3"
        />
    );
}

Two Variant Slots

The first item receives the first slot, all remaining items receive the second slot.

Preview

Get StartedLearn MoreContact Us

Code

import { LinkGroup } from "@/registry/rokkit200-ui/components/link-group/link-group";
import type { LinkItem } from "@/registry/rokkit200-ui/components/link/link";

const items: LinkItem[] = [
    {
        id: "1",
        label: "Get Started",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "2",
        label: "Learn More",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "3",
        label: "Contact Us",
        destination: { type: "internal", href: "#" },
    },
];

export default function LinkGroupTwoVariantsDemo() {
    return (
        <LinkGroup
            items={items}
            variantSlots={["primary", "secondary"]}
            className="flex gap-2"
            linkClassName="w-1/3"
        />
    );
}

Three Variant Slots

The first item receives the first slot, the second item receives the second slot, and all remaining items receive the third slot.

Preview

Get StartedLearn MoreContact Us

Code

import { LinkGroup } from "@/registry/rokkit200-ui/components/link-group/link-group";
import type { LinkItem } from "@/registry/rokkit200-ui/components/link/link";

const items: LinkItem[] = [
    {
        id: "1",
        label: "Get Started",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "2",
        label: "Learn More",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "3",
        label: "Contact Us",
        destination: { type: "internal", href: "#" },
    },
];

export default function LinkGroupThreeVariantsDemo() {
    return (
        <LinkGroup
            items={items}
            variantSlots={["primary", "secondary", "outline"]}
            className="flex gap-2"
            linkClassName="w-1/3"
        />
    );
}

Nav Container

When as="nav" is used, the container renders as a <nav> element with aria-label from navLabel for accessible labeling.

Preview

HomeAboutContact

Code

import { LinkGroup } from "@/registry/rokkit200-ui/components/link-group/link-group";
import type { LinkItem } from "@/registry/rokkit200-ui/components/link/link";

const items: LinkItem[] = [
    {
        id: "1",
        label: "Home",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "2",
        label: "About",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "3",
        label: "Contact",
        destination: { type: "internal", href: "#" },
    },
];

export default function LinkGroupAsNavDemo() {
    return (
        <LinkGroup
            items={items}
            as="nav"
            navLabel="Primary navigation"
            variantSlots={["primary", "secondary"]}
            className="flex gap-2 sm:flex-nowrap"
            linkClassName="w-1/3"
        />
    );
}

List Container

When as="ul" is used, each link is automatically wrapped in an <li> element for valid list markup.

Preview

• Home
• About
• Contact

Code

import { LinkGroup } from "@/registry/rokkit200-ui/components/link-group/link-group";
import type { LinkItem } from "@/registry/rokkit200-ui/components/link/link";

const items: LinkItem[] = [
    {
        id: "1",
        label: "Home",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "2",
        label: "About",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "3",
        label: "Contact",
        destination: { type: "internal", href: "#" },
    },
];

export default function LinkGroupAsUlDemo() {
    return (
        <LinkGroup
            items={items}
            as="ul"
            variantSlots={["outline"]}
            className="flex flex-col flex-wrap gap-y-2"
            linkClassName="w-full"
        />
    );
}

Invalid Item Resilience

Invalid items are forwarded to Link, which renders them as a non-interactive <span> fallback. No items are silently dropped or hidden.

Preview

Get StartedUnresolved LinkContact Us

Code

import { LinkGroup } from "@/registry/rokkit200-ui/components/link-group/link-group";
import type { LinkItem } from "@/registry/rokkit200-ui/components/link/link";

const items: LinkItem[] = [
    {
        id: "1",
        label: "Get Started",
        destination: { type: "internal", href: "#" },
    },
    {
        id: "2",
        label: "Unresolved Link",
        destination: { type: "invalid", reason: "Missing URL" },
    },
    {
        id: "3",
        label: "Contact Us",
        destination: { type: "internal", href: "#" },
    },
];

export default function LinkGroupInvalidItemDemo() {
    return (
        <LinkGroup
            items={items}
            variantSlots={["primary", "secondary", "outline"]}
            className="flex gap-2"
            linkClassName="w-1/3"
        />
    );
}

API Reference

Prop	Type	Default	Description
items	LinkItem[]	—	Ordered collection of normalized link items. All items render in authored order.
variantSlots	VariantSlot[]	["primary"]	Ordered variant emphasis array. Maps onto items by index position (see Variant Slot Resolution).
as	"div" | "ul" | "nav"	"div"	Container element. Consumer chooses semantic wrapper based on block context.
className	string	undefined	CSS classes applied to the container element.
linkClassName	string | Partial<Record<VariantSlot, string>> | ((variant: VariantSlot, index: number) => string)	undefined	Optional classes applied to each rendered Link. Supports a single class string, variant-keyed object map, or resolver function.
navLabel	string	undefined	aria-label for the container when as="nav". Required when using nav.

Variant Slot Resolution

The variantSlots array assigns visual emphasis to items by position. The rules are deterministic and do not depend on item content:

• 1 slot: all items use slots[0].
• 2 slots: index 0 uses slots[0], index 1+ uses slots[1].
• 3+ slots: index 0 uses slots[0], index 1 uses slots[1], index 2+ uses slots[2]. Extra slots beyond 3 are ignored.
• Default (no slots provided): all items receive "primary".

Container Semantics

• as="div" — default, no implicit semantic meaning.
• as="ul" — each Link is wrapped in <li> for valid list markup.
• as="nav" — renders <nav> with aria-label from navLabel. A dev warning is emitted when navLabel is omitted.

Accessibility

• Per-item accessibility is inherited entirely from Link.
• When as="nav", the container has an accessible label via navLabel → aria-label.
• When as="ul", valid <ul> / <li> semantics are maintained.
• Invalid items remain visible — Link renders them as non-interactive <span> elements.
• A dev warning is emitted when as="nav" is used without navLabel.

Related

• Link — per-item rendering, styling, accessibility, and fallback behavior
• Button — shared variant system and visual language