ionic-react-header-parallax

Easy-to-use React hook to add a parallax header effect to Ionic `IonHeader`.

Overview

ionic-react-header-parallax exposes a single hook: useIonHeaderParallax. Attach the returned ref to your IonHeader, and the hook handles:

• Header image expansion/collapse on scroll
• Toolbar background transitions
• Optional movement/styling of header buttons
• Dynamic title/button styles when collapsed

Video Examples

1.mp4	2.mp4
3.mp4	4.mp4

Existing YouTube demo: Watch on YouTube

Installation (npm)

npm install ionic-react-header-parallax --save

Installation (yarn)

yarn add ionic-react-header-parallax

Quick Start

import * as React from "react";
import {
  IonBackButton,
  IonButtons,
  IonContent,
  IonHeader,
  IonPage,
  IonTitle,
  IonToolbar,
} from "@ionic/react";
import { useIonHeaderParallax } from "ionic-react-header-parallax";

const Home: React.FC = () => {
  const { ref } = useIonHeaderParallax({
    image: "https://picsum.photos/1080",
    showBarButtons: true,
  });

  return (
    <IonPage>
      <IonHeader ref={ref}>
        <IonToolbar>
          <IonButtons slot="start">
            <IonBackButton defaultHref="/" />
          </IonButtons>
          <IonTitle>Post Title</IonTitle>
        </IonToolbar>
      </IonHeader>

      <IonContent className="ion-padding-start ion-padding-end">{/* Your page content */}</IonContent>
    </IonPage>
  );
};

export default Home;

API

useIonHeaderParallax(input)

Returns:

{
  ref: React.RefObject<any>
  loading: boolean
}

Input options:

Option	Type	Default	Description
image	string	required	Main image URL used for the expanded header.
defaultImage	string	image	Fallback image URL.
maximumHeight	number	300	Expanded header max height in pixels.
expandedColor	string	#313131	Overlay color behind/with image.
titleColor	string	#AAA	Title and button color (collapsed/managed states).
wait	number	300	Delay before initialization (ms). Useful for async page layout.
showBarButtons	boolean	false	Move IonButtons into image area while expanded.
buttonsToShow	"start" | "end"	undefined	Controls which slot buttons appear after collapse when showBarButtons is enabled.
titleStyle	Partial<CSSStyleDeclaration>	undefined	Custom inline style applied to IonTitle (collapsed state).
startButtonStyle	Partial<CSSStyleDeclaration>	undefined	Custom inline style applied to start IonButtons (collapsed state).
endButtonStyle	Partial<CSSStyleDeclaration>	undefined	Custom inline style applied to end IonButtons (collapsed state).

More Examples

1) Minimal setup

const { ref } = useIonHeaderParallax({
  image: "https://picsum.photos/1200/700",
});

2) Taller hero image + transparent toolbar when expanded

const { ref } = useIonHeaderParallax({
  image: "https://picsum.photos/1600/900",
  maximumHeight: 420,
  expandedColor: "#111",
  titleColor: "#fff",
});

3) Keep action buttons visible in expanded header

const { ref } = useIonHeaderParallax({
  image: "https://picsum.photos/1500/900",
  showBarButtons: true,
  buttonsToShow: "end",
  endButtonStyle: { marginRight: "8px" },
});

4) Dynamic image updates

const [cover, setCover] = React.useState("https://picsum.photos/1400/800");
const { ref, loading } = useIonHeaderParallax({
  image: cover,
  wait: 100,
});

Requirements

• An IonPage wrapper
• An IonHeader containing at least one IonToolbar
• An IonContent in the same page

Troubleshooting

• If nothing happens, verify ref is attached to IonHeader.
• If styles look wrong, ensure Ionic core CSS is loaded in your app.
• If content overlaps, check custom CSS that alters IonContent scroll container.

Documentation Notes

• Start from the Quick Start section, then adjust behavior using the options listed in API.
• Use showBarButtons and buttonsToShow when you want action buttons in the expanded header.
• Use wait when your layout depends on async data and header initialization happens too early.
• Review More Examples and the videos/ clips together to map each configuration to scroll behavior.

License

MIT