Skip to main content

Theme Shell and Scroll

Role​

ReactWP's theme shell is the fixed markup and container structure that the frontend runtime expects.

This part matters because:

  • the loader needs a real DOM node before React mounts
  • the smoother needs stable wrapper and content IDs
  • portal-mounted UI such as the header must know where to render

Main Files​

  • src/themes/reactwp/template/header.php
  • src/themes/reactwp/template/footer.php
  • src/themes/reactwp/template/functions.php
  • src/themes/reactwp/js/inc/AppShell.jsx
  • src/themes/reactwp/js/inc/Scroller.js
  • src/themes/reactwp/js/components/Header.jsx

Shell Markup​

The default shell currently includes:

  • #reactwp-bootstrap
  • #loader
  • #app-header
  • #viewport
  • #pageWrapper
  • #pageContent
  • #app

At a high level:

  • #reactwp-bootstrap holds the initial JSON payload
  • #loader is the first-load overlay
  • #app-header is the default portal mount for the React header
  • #viewport is the outer transition target
  • #pageWrapper and #pageContent are the smooth-scroll wrapper and content nodes
  • #app is where React mounts

Smooth Scroll Structure​

Scroller.js creates ScrollSmoother with:

  • wrapper: '#pageWrapper'
  • content: '#pageContent'

That means #pageContent is the transformed scroll layer.

Anything that should stay fixed outside that transformed layer should not live inside #pageContent.

Why The Header Uses A Portal​

Header.jsx is rendered from React, but it portals into #app-header.

That keeps the header:

  • controlled by React
  • outside the smoother
  • suitable for fixed positioning and shell-level UI

Custom Header Mounts​

Header.jsx accepts mountId.

If you change it, the matching node must exist in the PHP shell markup.

That mount node should stay outside:

  • #pageWrapper
  • #pageContent

Otherwise the header becomes part of the smoother layer and loses the main benefit of the portal.

Footer.jsx is different from Header.jsx.

The footer stays inside the app shell and scrolls with page content by default.

Critical Shell Styling​

functions.php prints a small amount of inline CSS in wp_head.

That critical shell CSS exists so the user can immediately see:

  • the page background
  • the loader
  • the minimum shell sizing

before the compiled theme stylesheet is fully applied.

The full theme styling still comes from the compiled CSS asset.