Built-in Components

VitePress Carbon ships every component it uses internally, and all of them can be imported into your own pages, layouts, and components from a single entry point:

import { VPButton, VPBadge, VPTeamMembers } from 'vitepress-carbon/components'

No global registration

Unlike the VitePress default theme, Carbon does not register any component globally. To use a component you either import it locally in a <script setup> block, or register it yourself in enhanceApp (see Registering components globally).

Using components in Markdown

Every Markdown page is compiled to a Vue component, so you can add a <script setup> block and use any component directly:

---
title: My Page
---

<script setup>
import { VPButton, VPBadge } from 'vitepress-carbon/components'
</script>

# My Page <VPBadge type="tip" text="new" />

<VPButton text="Get Started" href="/guide/getting-started" theme="brand" />

Registering components globally

If you use a component on many pages, register it once in your theme entry and use it anywhere without importing:

// .vitepress/theme/index.js
import { VPCarbon } from 'vitepress-carbon'
import { VPButton, VPBadge } from 'vitepress-carbon/components'

export default {
  ...VPCarbon,
  enhanceApp({ app }) {
    app.component('VPButton', VPButton)
    app.component('Badge', VPBadge)
  }
}

<!-- now works in any .md file, no import needed -->
<VPButton text="Download" href="/download" />

Component reference

The components below are the ones intended for direct use in pages and custom layouts. Everything else exported from vitepress-carbon/components (navbar, sidebar, search, etc.) is an internal building block — you can import those too, but their props may change between minor versions.

VPButton

A link-styled button. Renders an <a> when href is set, otherwise a <button>. External links automatically get target="_blank" and rel="noreferrer".

<VPButton text="Get Started" href="/guide/getting-started" />
<VPButton
  text="View on GitHub"
  href="https://github.com/brenoepics/vitepress-carbon"
  theme="alt"
  size="big"
/>

Prop	Type	Default	Description
text	string	— (required)	The button label.
href	string	undefined	Destination URL. Renders an <a> when set.
theme	'brand' | 'alt' | 'sponsor'	'brand'	Visual style.
size	'medium' | 'big'	'medium'	Button size.
tag	string	undefined	Force a specific HTML tag.
target	string	auto	Link target. Auto-set for external links.
rel	string	auto	Link rel. Auto-set for external links.

VPBadge

A small inline badge, useful next to headings to mark new or deprecated features.

### My Feature
<VPBadge type="warning" text="beta" />
<VPBadge type="danger">deprecated</VPBadge>

Prop	Type	Default	Description
text	string	undefined	Badge label. The default slot overrides it.
type	'info' | 'tip' | 'warning' | 'danger'	'tip'	Color variant.

VPImage

A theme-aware image. Accepts a plain src string, an object with extra attributes, or a { light, dark } pair that swaps automatically with the color scheme. Paths are resolved against your site base.

<VPImage image="/logo.svg" alt="Logo" />
<VPImage
  :image="{ light: '/logo-light.svg', dark: '/logo-dark.svg', alt: 'Logo' }"
/>

Prop	Type	Default	Description
image	string | { src, alt? } | { light, dark, alt? }	— (required)	Image source(s).
alt	string	undefined	Alt text (overrides image.alt).

VPLink

A smart link that renders an <a> when href is set (with automatic external link handling and icon) and a <span> otherwise.

<VPLink href="https://vitepress.dev">VitePress</VPLink>
<VPLink href="https://vitepress.dev" no-icon>VitePress (no icon)</VPLink>

Prop	Type	Default	Description
href	string	undefined	Destination URL.
noIcon	boolean	false	Hide the external-link icon.
tag	string	auto	Force a specific HTML tag.
target	string	auto	Link target. Auto-set for external links.
rel	string	auto	Link rel. Auto-set for external links.

VPHighlight

The glowing gradient highlight used by the home hero (see Home Page).

Prop	Type	Default	Description
glowingActive	boolean	false	Enables the glow animation.
glowingIcon	string	var(--vp-c-brand-3)	Glow background color.
stringHighlightColors	string[]	['transparent', 'var(--vp-c-brand-1)', 'var(--vp-c-brand-3)']	Gradient stops of the vertical line.
icon	string | object	code icon	Icon shown inside the highlight.

VPFeatures

The feature-card grid used on the home page. The grid automatically picks 2, 3, 4, or 6 columns based on the number of items.

<script setup>
import { VPFeatures } from 'vitepress-carbon/components'

const features = [
  { icon: '⚡', title: 'Fast', details: 'Instant server start.' },
  {
    icon: '🎨',
    title: 'Themeable',
    details: 'CSS variables everywhere.',
    link: '/guide/configuration',
    linkText: 'Configure'
  }
]
</script>

<VPFeatures :features="features" />

Each feature item supports:

Field	Type	Description
title	string	Card title (required).
details	string	Card body text (required). Supports raw HTML.
icon	string | { src, alt? } | { light, dark }	Emoji, raw SVG string, or image source(s).
link	string	Makes the whole card a link.
linkText	string	Call-to-action text shown at the card bottom.
rel / target	string	Link attributes.

VPHero

The hero banner. Normally driven by home page frontmatter, but usable standalone in custom layouts:

<VPHero
  name="My Project"
  text="A tagline headline"
  tagline="Longer supporting text"
  :actions="[
    { theme: 'brand', text: 'Get Started', link: '/guide/' },
    { theme: 'alt', text: 'GitHub', link: 'https://github.com/...' }
  ]"
/>

Prop	Type	Description
name	string	Brand-colored first line.
text	string	Main headline.
tagline	string	Supporting text below the headline.
image	ThemeableImage	Image shown beside the hero text.
actions	{ theme?, text, link, target?, rel? }[]	Action buttons.
icon	string | object	Icon for the glowing highlight.

VPTeamPage, VPTeamPageTitle, VPTeamPageSection, VPTeamMembers

Components for building a team page, typically combined on a page with layout: page:

---
layout: page
---

<script setup>
import {
  VPTeamPage,
  VPTeamPageTitle,
  VPTeamMembers
} from 'vitepress-carbon/components'

const members = [
  {
    avatar: 'https://github.com/brenoepics.png',
    name: 'Breno A.',
    title: 'Creator',
    links: [
      { icon: 'github', link: 'https://github.com/brenoepics' }
    ]
  }
]
</script>

<VPTeamPage>
  <VPTeamPageTitle>
    <template #title>Our Team</template>
    <template #lead>The people behind the project.</template>
  </VPTeamPageTitle>
  <VPTeamMembers :members="members" />
</VPTeamPage>

VPTeamMembers props:

Prop	Type	Default	Description
members	TeamMember[]	— (required)	Members to display.
size	'small' | 'medium'	'medium'	Card size.

Each TeamMember:

Field	Type	Description
avatar	string	Avatar image URL (required).
name	string	Member name (required).
title	string	Role or title.
org	string	Organization name.
orgLink	string	Organization URL.
desc	string	Short description.
links	SocialLink[]	Social links ({ icon, link }).
sponsor	string	Sponsor URL — shows a sponsor button.
actionText	string	Sponsor button text.

VPSponsors

Renders sponsor logos in a grid, either as a flat list or grouped by tier.

<script setup>
import { VPSponsors } from 'vitepress-carbon/components'

const sponsors = [
  {
    tier: 'Gold Sponsors',
    size: 'big',
    items: [
      { name: 'Company', url: 'https://example.com', img: '/sponsor.svg' }
    ]
  }
]
</script>

<VPSponsors :data="sponsors" />

Prop	Type	Default	Description
data	Sponsors[] | Sponsor[]	undefined	Tiered groups or a flat sponsor list.
mode	'normal' | 'aside'	'normal'	Layout mode.
tier	string	undefined	Tier label (flat list only).
size	GridSize	undefined	Logo size (flat list only).

VPSocialLinks

The social-icon row used in the navbar, reusable anywhere:

<script setup>
import { VPSocialLinks } from 'vitepress-carbon/components'

const links = [
  { icon: 'github', link: 'https://github.com/brenoepics/vitepress-carbon' },
  { icon: 'x', link: 'https://x.com/example' },
  {
    icon: { svg: '<svg>...</svg>' },
    link: 'https://example.com',
    ariaLabel: 'Custom'
  }
]
</script>

<VPSocialLinks :links="links" />

Prop	Type	Description
links	SocialLink[]	icon is a built-in name (github, discord, x, …) or { svg }.

VPFooter

The site footer: an optional call to action, a message and a copyright line, with contribution-graph tiles bleeding off either edge. It renders only on pages without a sidebar, and is driven entirely by themeConfig.footer — you normally configure it rather than importing it.

// .vitepress/config.mts
themeConfig: {
  footer: {
    action: {
      text: 'Create Repository',
      link: 'https://github.com/new',
      theme: 'brand' // 'brand' | 'alt' | 'sponsor', defaults to 'brand'
    },
    message: 'Released under the <a href="/LICENSE">MIT License</a>.',
    copyright: `Copyright © 2024–${new Date().getFullYear()} You`
  }
}

Key	Type	Description
action	object	Optional CTA above the message. Omit to hide it.
message	string	Supports inline HTML.
copyright	string	Supports inline HTML.

Set footer: false in a page's frontmatter to hide it on that page.

VPContributionTiles

The decorative grid behind the footer — a GitHub contribution graph rendered from a deterministic hash, so the server and client always produce the same pattern. Useful on its own for any band that wants the same texture.

mask="frame" punches an ellipse out of the middle, leaving the grid continuous around all four edges — this is what the footer uses, so the tiles close around the content instead of stopping at a hard edge. The hollow is sized with --vp-tiles-hollow-w / --vp-tiles-hollow-h (defaults 40% and 62%), which is how the footer widens it on narrow screens.

<script setup>
import { VPContributionTiles } from 'vitepress-carbon/components'
</script>

<VPContributionTiles mask="frame" :columns="120" :rows="18" />
<VPContributionTiles mask="fade" side="left" :columns="20" :rows="7" />

Prop	Type	Default	Description
mask	'fade' | 'frame' | 'none'	'fade'	frame hollows out the centre; fade thins to one edge.
side	'left' | 'right'	'left'	Edge to fade towards. Only used when mask is fade.
columns	number	16	Grid width in cells.
rows	number	7	Grid height. Seven matches a real weekday graph.

The five activity levels are themable via --vp-c-tile-0 … --vp-c-tile-4. Level 0 is transparent by default so the grid tints nothing behind it.

Composables

The theme entry also exports two composables:

import { useSidebar, useLocalNav } from 'vitepress-carbon'

const { hasSidebar, isOpen, open, close } = useSidebar()
const { hasLocalNav, headers } = useLocalNav()

They are handy inside custom layouts to react to the current page structure — for example hiding an element when the sidebar is visible.

Next steps

• Creating Components — build your own components on top of the theme.
• Custom Layouts — build full-page layouts like a blog.