n-anchor

Anchor component for navigation and table of contents. Invoke when user needs to implement anchor navigation, table of contents, or scroll-based navigation highlighting in Naive UI.

SKILL.md

GitHub

Naive UI Anchor Component

Anchor component for navigation and table of contents. Tells users where they are on the page.

When to Use

Use this component when:

  • Documentation pages: Navigate between sections in documentation
  • Table of contents: Show current reading position in long articles
  • Single page navigation: Navigate between sections on the same page
  • Form wizards: Track progress through multi-section forms

When to Invoke

Invoke this skill when:

  • User needs to implement anchor navigation
  • User wants a table of contents with scroll highlighting
  • User needs to track scroll position and highlight active section
  • User wants to combine anchor with affix behavior
  • User asks about scroll-to functionality

Features

  • Scroll Tracking: Automatically highlights current section based on scroll
  • Nested Links: Support for hierarchical navigation structure
  • Affix Mode: Can work as an affix component
  • Custom Styling: Configurable rail and background display
  • Manual Scroll: Programmatic scroll to specific sections
  • Gap Handling: Option to ignore gap for precise positioning

API Reference

Anchor Props

Name Type Default Description
affix boolean false If it works like an affix. If set to true, it will receive props from Affix.
bound number 12 The height of the border when scrolling.
ignore-gap boolean false If set to true, it will be displayed on the exact href.
offset-target string | HTMLElement | Window | Document | (() => HTMLElement) document The element or selector used to calc offset of link elements.
show-rail boolean true Whether to show the sider rail.
show-background boolean true Whether to show background of links.
type 'rail' | 'block' 'rail' The type to use.

AnchorLink Props

Name Type Default Description
href string undefined The target of link
title string undefined The content of link

AnchorLink Slots

Name Parameters Description Version
title () The title of the link. 2.42.0

Anchor Methods

Name Type Description
scrollTo (href: string) => void Manually scroll to the specific position.

Basic Usage

Basic Anchor

<template>
  <n-anchor :show-rail="showRail" :show-background="showBackground">
    <n-anchor-link title="Demos" href="#Demos">
      <n-anchor-link title="Basic" href="#basic.vue" />
      <n-anchor-link title="Ignore-Gap" href="#ignore-gap.vue" />
      <n-anchor-link title="Affix" href="#affix.vue" />
      <n-anchor-link title="Scroll To" href="#scrollto.vue" />
    </n-anchor-link>
    <n-anchor-link title="API" href="#API" />
  </n-anchor>
</template>

<script setup>
import { ref } from 'vue'

const showRail = ref(true)
const showBackground = ref(true)
</script>

Anchor with Affix

<template>
  <n-anchor
    affix
    listen-to=".document-scroll-container"
    :trigger-top="24"
    :top="88"
    style="z-index: 1"
    :bound="24"
  >
    <n-anchor-link title="Demos" href="#Demos">
      <n-anchor-link title="Basic" href="#basic.vue" />
      <n-anchor-link title="Ignore-Gap" href="#ignore-gap.vue" />
    </n-anchor-link>
    <n-anchor-link title="API" href="#API" />
  </n-anchor>
</template>

Ignore Gap Mode

<template>
  <n-anchor affix :trigger-top="24" :top="88" style="z-index: 1" ignore-gap>
    <n-anchor-link title="Demos" href="#Demos">
      <n-anchor-link title="Basic" href="#basic.vue" />
      <n-anchor-link title="Ignore-Gap" href="#ignore-gap.vue" />
    </n-anchor-link>
    <n-anchor-link title="API" href="#API" />
  </n-anchor>
</template>

Common Patterns

Programmatic Scroll

<template>
  <div>
    <n-anchor
      ref="anchorRef"
      affix
      :trigger-top="24"
      :top="88"
      :bound="24"
      style="z-index: 1"
    >
      <n-anchor-link title="Demos" href="#Demos">
        <n-anchor-link title="Basic" href="#basic.vue" />
        <n-anchor-link title="Affix" href="#affix.vue" />
      </n-anchor-link>
      <n-anchor-link title="API" href="#API" />
    </n-anchor>
  </div>
  <n-space>
    <n-button @click="scrollTo('#basic.vue')">
      Basic
    </n-button>
    <n-button @click="scrollTo('#affix.vue')">
      Affix
    </n-button>
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const anchorRef = ref(null)

const scrollTo = (href) => {
  anchorRef.value?.scrollTo(href)
}
</script>

Block Type Anchor

<template>
  <n-anchor type="block">
    <n-anchor-link title="Introduction" href="#intro" />
    <n-anchor-link title="Installation" href="#installation" />
    <n-anchor-link title="Usage" href="#usage" />
  </n-anchor>
</template>

Custom Offset Target

<template>
  <div ref="scrollContainer" class="scroll-container">
    <n-anchor :offset-target="() => scrollContainer">
      <n-anchor-link title="Section 1" href="#section1" />
      <n-anchor-link title="Section 2" href="#section2" />
    </n-anchor>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const scrollContainer = ref(null)
</script>

Best Practices

  1. Use with long content: Anchor works best with pages that have multiple sections

  2. Set proper bound value: Adjust bound to control when anchor links highlight

  3. Combine with Affix: Use affix prop to keep anchor visible while scrolling

  4. Match href with element IDs: Ensure href values match actual element IDs on the page

  5. Use nested links for hierarchy: Create nested anchor links for subsections

  6. Consider ignore-gap: Use ignore-gap for precise positioning without offset