Component Replacement

About 3 min

Replace theme components using alias when { custom: true } is set in behavior options.

Alias Configuration

Configure component replacement in your VuePress config:

.vuepress/config.ts
import { getDirname
, path
 } from "vuepress/utils";
import { hopeTheme
 } from "vuepress-theme-hope";

const __dirname
 = getDirname
(import.meta.url
);

export default {
  theme
: hopeTheme
(
    {
      // your theme config here
    },
    { custom
: true },
  ),

  alias
: {
    // Replace theme components with custom implementations
    // For example, here we change the theme's home page component to HomePage.vue under user .vuepress/components
    "@theme-hope/components/home/HomePage": path
.resolve
(
      __dirname
,
      "./components/HomePage.vue",
    ),
  },
};

For components with slots, you can import them and customize content through slots.

Theme Alias

Base Components

@theme-hope/components/base/AutoLink: basic link
Slots: default, before, after
@theme-hope/components/base/BreadCrumb: breadcrumb
@theme-hope/components/base/EditIcon: edit icon
@theme-hope/components/base/MainFadeInUpTransition: main layout transition
Slots: default
@theme-hope/components/base/MainLayout: main layout
Slots: default, navScreenTop, navScreenBottom, sidebarItems, sidebarTop, sidebarBottom
- navScreenTop navScreenBottom slots are piped to NavBar component.
- sidebarItems, sidebarTop, sidebarBottom slots are piped to Sidebar component.
@theme-hope/components/base/MarkdownContent: Markdown content
Slots: contentBefore, contentAfter
@theme-hope/components/base/PageContent: main page content
Slots: pageTop, pageBottom, content, contentBefore, contentAfter, toc, tocBefore, tocAfter
- contentBefore, contentAfter slots are piped to MarkdownContent component.
- toc, tocBefore, tocAfter slots are piped to TOC component.
@theme-hope/components/base/PageFooter: page footer
@theme-hope/components/base/PrintButton: print button
@theme-hope/components/base/PageNav: page navigation
@theme-hope/components/base/PageTitle: page title
@theme-hope/components/base/SkipLink: link pointing to main content
@theme-hope/components/base/TOC: table of contents
Slots: toc, tocBefore, tocAfter

Home Page Components

@theme-hope/components/home/FeatureSection: homepage feature section
@theme-hope/components/home/HighlightSection: homepage highlight section
@theme-hope/components/home/HeroInfo: homepage logo and introduction
Slots: heroInfo, heroLogo, heroBg
- heroInfo slot receives text tagline isFullScreen and style props.
- heroLogo slot receives image imageDark alt and style props.
- heroBg slot receives image imageDark and style props.
@theme-hope/components/home/HeroSlideDownButton: hero slide down button
@theme-hope/components/home/HomePage: default home page (project home page)
Slots: heroInfo, heroLogo, heroBg, heroBefore, heroAfter, content, contentBefore, contentAfter
- heroInfo, heroLogo, heroBg slots are piped to HeroInfo component.
- contentBefore, contentAfter slots are piped to MarkdownContent component.
@theme-hope/components/home/PortfolioHero: portfolio hero
Slots: portfolioInfo, portfolioAvatar, portfolioBg
- portfolioInfo slot receives name welcome title titles and links props.
- portfolioAvatar slot receives avatar avatarDark style and alt props.
- portfolioBg slot receives image imageDark and style props.
@theme-hope/components/home/PortfolioHome: portfolio home page
Slots: portfolioInfo, portfolioAvatar, portfolioBg
- portfolioInfo, portfolioAvatar, portfolioBg slots are piped to PortfolioHero component.

@theme-hope/components/navbar/I18nIcon: i18n icon
@theme-hope/components/navbar/LanguageDropdown: language dropdown
@theme-hope/components/navbar/Navbar: navbar component
Slots: navScreenTop, navScreenBottom
- navScreenTop navScreenBottom slots are piped to NavBar component.
@theme-hope/components/navbar/NavbarBrand: navbar brand information
@theme-hope/components/navbar/NavbarDropdown: dropdown list
Slots: title
@theme-hope/components/navbar/NavbarLinks: navbar links
@theme-hope/components/navbar/NavScreen: navigation screen in mobile view
Slots: navScreenTop, navScreenBottom
@theme-hope/components/navbar/NavScreenLinks: mobile view navbar links
@theme-hope/components/navbar/NavScreenMenu: mobile view navbar dropdown menu
@theme-hope/components/navbar/RepoLink: repository link
@theme-hope/components/navbar/ToggleNavbarButton: navbar toggle button
@theme-hope/components/navbar/ToggleSidebarButton: sidebar toggle button

@theme-hope/components/sidebar/Sidebar: sidebar
Slots: sidebarItems, sidebarTop, sidebarBottom
- sidebarItems slot receives sidebarItems prop.
@theme-hope/components/sidebar/SidebarChild: sidebar link item
@theme-hope/components/sidebar/SidebarGroup: sidebar grouping links
@theme-hope/components/sidebar/SidebarLinks: sidebar links

Info Components

@theme-hope/components/info/AuthorInfo: author information
@theme-hope/components/info/CategoryInfo: category information
@theme-hope/components/info/DateInfo: date information
@theme-hope/components/info/OriginalInfo: original mark
@theme-hope/components/info/PageInfo: page information
@theme-hope/components/info/PageMeta: page meta information
@theme-hope/components/info/PageViewInfo: page views information
@theme-hope/components/info/ReadingTimeInfo: reading time information
@theme-hope/components/info/TagInfo: tag information
@theme-hope/components/info/WordInfo: word information
@theme-hope/components/info/icons: info icons

Appearance Components

@theme-hope/components/appearance/AppearanceButton: appearance button
@theme-hope/components/appearance/AppearanceIcon: appearance icon
@theme-hope/components/appearance/AppearanceSettings: appearance settings
@theme-hope/components/appearance/ColorMode: color mode
@theme-hope/components/appearance/ColorModeSwitch: color mode switch
@theme-hope/components/appearance/ThemeColor: theme color
@theme-hope/components/appearance/ThemeColorPicker: theme color picker
@theme-hope/components/appearance/ToggleFullScreen: fullscreen toggle
@theme-hope/components/appearance/ToggleFullScreenButton: fullscreen toggle button

Transition Components

@theme-hope/components/transition/DropTransition: drop transition component
Slots: default

Blog Components

@theme-hope/components/blog/ArticleItem: article item
Slots: articleTitle, articleCover, articleInfo, articleExcerpt
- articleTitle slot receives title isEncrypted and type props.
- articleCover slot receives cover props.
- articleInfo slot receives author category tag date isOriginal pageview readingTime and readingTimeLocale props.
- articleExcerpt slot receives excerpt props.
@theme-hope/components/blog/ArticleList: article list
Slots: articleTitle, articleCover, articleInfo, articleExcerpt
- articleTitle, articleCover, articleInfo, articleExcerpt slots are piped to ArticleItem component.
@theme-hope/components/blog/ArticlesInfo: article info
@theme-hope/components/blog/ArticleType: article type
@theme-hope/components/blog/BloggerInfo: blogger info
Slots: bloggerInfo
- bloggerInfo slot receives name avatar and description props.
@theme-hope/components/blog/BlogHero: blog homepage logo and introduction
Slots: heroInfo, heroLogo, heroBg,
- heroBg slot receives text tagline isFullScreen and style props.
- heroLogo slot receives image imageDark alt and style props.
- heroBg slot receives image imageDark and style props.
@theme-hope/components/blog/BlogHome: blog home
Slots: heroInfo, heroLogo, heroBg, heroBefore, heroAfter, articleCover, articleTitle, articleInfo, articleExcerpt, bloggerInfo, infoBefore, infoAfter, content, contentBefore, contentAfter
- heroInfo, heroLogo, heroBg slots are piped to BlogHero component.
- articleTitle, articleCover, articleInfo, articleExcerpt slots are piped to ArticleList component.
- bloggerInfo slot is piped to BloggerInfo component.
- infoBefore, infoAfter slots are piped to InfoPanel component.
- contentBefore, contentAfter slots are piped to MarkdownContent component.
@theme-hope/components/blog/BlogMainLayout: blog main layout
Slots: default, navScreenTop, navScreenBottom, sidebarItems, sidebarTop, sidebarBottom, bloggerInfo
- navScreenTop, navScreenBottom slots are piped to NavBar component.
@theme-hope/components/blog/CategoriesInfo: Category info
@theme-hope/components/blog/CategoryList: Category list
@theme-hope/components/blog/CategoryPage: category page
Slots: default, articleTitle, articleCover, articleInfo, articleExcerpt, articleBefore, articleAfter, bloggerInfo, infoBefore, infoAfter
- articleTitle, articleCover, articleInfo, articleExcerpt slots are piped to ArticleList component.
- bloggerInfo slot is piped to BloggerInfo component.
- infoBefore, infoAfter slots are piped to InfoPanel component.
@theme-hope/components/blog/InfoList: blog info list
Slots: bloggerInfo, infoBefore, infoAfter
@theme-hope/components/blog/InfoPanel: blog info panel
- bloggerInfo slot is piped to BloggerInfo component.
@theme-hope/components/blog/Pagination: pagination
@theme-hope/components/blog/ProjectPanel: blog homepage project panel
@theme-hope/components/blog/SocialMedias: social media links
@theme-hope/components/blog/TagList: tag list
@theme-hope/components/blog/TagPage: tag page
@theme-hope/components/blog/TagsInfo: tag info
@theme-hope/components/blog/TimelineItems: timeline items
@theme-hope/components/blog/TimelineList: timeline List
@theme-hope/components/blog/TimelinePage: timeline page
Slots: articleBefore, articleAfter, bloggerInfo, infoBefore, infoAfter
- bloggerInfo slot is piped to BloggerInfo component.
- infoBefore, infoAfter slots are piped to InfoPanel component.
@theme-hope/components/blog/TypePage: type page
Slots: default, articleTitle, articleCover, articleInfo, articleExcerpt, articleBefore, articleAfter, bloggerInfo, infoBefore, infoAfter
- articleTitle, articleCover, articleInfo, articleExcerpt slots are piped to ArticleList component.
- bloggerInfo slot is piped to BloggerInfo component.
- infoBefore, infoAfter slots are piped to InfoPanel component.
@theme-hope/components/blog/icons: blog icons

Encryption Components

@theme-hope/modules/encrypt/components/GlobalEncrypt: global encrypt wrapper
Slots: default
@theme-hope/modules/encrypt/components/LocalEncrypt: local encrypt wrapper
Slots: default
@theme-hope/modules/encrypt/components/PasswordModal: password input box

Others

Composables, layouts, utils can be also replaced via alias, check theme source code for details.

Changelog

7/9/25, 4:17 AM

View All Changelog

05fbb-build: bump depson 7/9/25
2a19e-docs: tweakson 6/4/25
1e9f5-feat(theme): update file structure and rebuild alias (#4875)on 5/7/25
98fc7-feat(theme)!: rebuild heroHeight as heroStyleon 4/13/25
329ae-feat(theme): add heroHeighton 4/9/25
f3e43-chore: bump depson 3/5/25
b1230-docs(theme): add twoslashon 2/18/25
f7910-fix(theme): fix InfoPanel animationon 1/24/25
edfd5-feat(theme): use plugin-iconon 1/7/25
f565a-feat(theme)!: remove navbar slots as they can be achieved with navbarLayout optionon 12/16/24
2c32a-docs: update docson 9/23/24
6ad69-feat: implement theme guidelines and use official plugins (#4453)on 9/20/24
9ff54-feat(theme): make portfolio a common layouton 5/11/24
e788a-chore(theme): add vp prefix for some componentson 4/30/24
6c081-feat(theme): add portfolio homepageon 4/29/24
95ac5-feat(theme): update slot nameon 4/29/24
3360a-chore(theme): tweakson 4/7/24
f9d00-chore(theme): update blog heroon 3/3/24
54c46-docs: update docson 1/26/24
05f91-feat: bump to vp2rc2on 1/26/24
2f38e-docs(theme): update docson 11/9/23
794f9-chore: update depson 7/6/23
31bea-docs(theme): update docson 5/31/23
d7e50-feat(theme): add heroImageStyle bgImage and bgImageStyle for project homepageon 5/29/23
c2e16-docs(theme): update docson 5/27/23
fa8bb-docs(theme): fix typoson 5/24/23
2a306-docs: fix typos, grammar, and other minor issues (#3049)on 4/21/23
39704-fix(theme): stop using style as propon 4/19/23
a0afc-fix(theme): support heroImageDark and improve slotson 4/15/23
f314f-feat(theme): add heroBg and heroInfo slot for BlogHeroon 4/12/23
92fc8-feat(theme): use performance version by defaulton 4/12/23
21d14-docs(theme): update docson 4/10/23
9a137-feat(theme): add title, cover, info and excerpt slot for articleon 4/10/23
f1436-fix(theme): revert "fix(theme): fix slots name"on 2/27/23
96e01-fix(theme): fix slots nameon 2/26/23
74d2f-feat(theme): add before and after slot for tocon 2/17/23
bade3-feat(auto-catalog): add icon sloton 2/15/23
8174c-docs(theme): use fontawesomeon 1/18/23
a0c8a-docs(theme): update docson 1/17/23
aafa6-feat(theme): update navbarLayout option and slot nameson 1/17/23
42b11-feat(theme): improve layout, close #2639on 1/6/23
3f76b-feat(theme): rebuild home page related componentson 1/4/23
c4fe2-chore(theme): tweakson 12/18/22
79ac6-feat(theme): remove alias .js extensionon 12/14/22
8e2fc-feat(theme): remove slots in BlogHero and correct docs, fix #2503on 12/8/22
2243a-chore: fix typoson 11/1/22
13530-fix(theme): fix navbar sloton 10/11/22
ad675-docs: fix __dirnameon 10/11/22
4659f-docs: improve docs, close #2190on 9/9/22
2fa50-feat: migrate to ESM (#2158)on 8/28/22
393ff-fix(theme): fix slot nameon 5/29/22
23515-docs: update codetabon 5/21/22
9cdd7-feat(md-enhance): change @codetab to @tabon 5/20/22
63d09-feat(md-enhance): rebuild codegroupon 5/19/22
ad023-docs: fix typoson 5/19/22
7f1ab-docs(theme): update docson 5/19/22
22000-docs(theme): update docson 5/15/22
fd395-docs: update related docson 5/3/22
73de5-docs: update docson 4/15/22
fc15c-docs: update docson 4/15/22
da2ed-feat(theme): add slots for HomeHeroon 4/9/22
21000-docs(theme): update cookbookon 4/3/22
bcf02-docs: update docson 3/25/22
716f9-chore: add demoson 3/24/22
f6ff0-docs(theme): update categories and tagson 2/26/22
95ff3-docs(theme): update docson 2/22/22
37324-docs(theme): update docson 2/22/22

Contributors

Mr.Hope

Nan Huang