Replace Components

About 3 min

When setting { custom: true } in Behavior options, the theme will import components through @theme-hope alias, so you can use it to replace any component of the theme.

How to Replace via Alias

You need to replace the component alias used in the theme with alias option in your own VuePress config file.

.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
: {
    // Here you can redirect aliases to your own components
    // 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",
    ),
  },
};

Some components provide slots, in this case, you can directly import the original component when overriding the component, and pass in the content you need through the slot.

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

5/7/25, 7:29 PM

View All Changelog

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