#5210·vitepress

Centered layout option for Home Hero section (Desktop)

Author: ChisakaKanakoCreated Jun 6, 2026Updated Sep 15, 2026
Labelsthemestale

Is your feature request related to a problem? Please describe.

I want to design a classic, centrally aligned landing page (e.g., a large project logo/image on top, with the title, tagline, and action buttons centered directly below it). While mobile views naturally stack these elements, achieving this same centered effect on desktop requires writing a significant amount of custom CSS to forcefully override VitePress's internal styles.

Describe the solution you'd like

I would like to propose a new native configuration option in the frontmatter for the Hero section.

For example, adding an align: 'center' property to the hero object:

---
layout: home
hero:
  align: center # <-- New proposed property
---

When this property is enabled, the VPHomeHero component would natively render using a flex-direction: column and align-items: center layout on desktop views. The image would sit nicely above the text, and the ambient background glow (.image-bg) would remain perfectly anchored behind the image.

Describe alternatives you've considered

Custom CSS: I have successfully achieved this by writing custom CSS to override the default layout.

Component Override: Completely replacing VPHomeHero.

Additional context

Here is the working custom CSS I am currently using as a workaround (Proof of Concept). It achieves the exact desired layout on desktop views.

@media not all and (max-width: 768px) {
  .VPHome .VPHomeHero.has-image .container {
    flex-direction: column !important;
    align-items: center !important;
    text-align: center !important;
  }

  .VPHome .VPHomeHero.has-image .image {
    order: 1 !important;
    margin: 0 0 32px !important;
  }

  .VPHome .VPHomeHero.has-image .main {
    order: 2 !important;
    width: 100% !important;
    max-width: none !important;
  }

  .VPHome .VPHomeHero .image-container {
    position: relative !important;
    transform: none !important;
    width: 512px !important;
    height: auto !important;
  }

  .VPHome .VPHomeHero .image-src {
    position: static !important;
    transform: none !important;
    margin-inline: auto !important;
  }

  .VPHome .VPHomeHero .heading {
    display: block !important;
  }

  .VPHome .VPHomeHero .name::after {
    content: " ";
  }

  .VPHome .VPHomeHero .tagline {
    margin-inline: auto !important;
  }

  .VPHome .VPHomeHero .actions {
    justify-content: center !important;
  }
}
Before After Reference
Image Image Image

A native frontmatter option would make creating centered landing pages much easier for the community. Thank you for considering this!

Validations