Customization#

Start with the zero-effort default and adopt customization only as far as you need.

Default — works from scratch#

Renders the complete HAAPI flow UI.

Styles customization#

The UI components emit plain .haapi-stepper-* CSS class names — restyle the default UI just by overriding those classes in your own stylesheet, no code changes needed.

CSS customization#

The HAAPI UI components are styled via plain CSS class names — no CSS-in-JS, no inline styles. The components only emit class names; the actual rules live in a stylesheet shipped alongside the host application’s global stylesheet. For example, in the case of the haapi-react-app, in haapi-react-app/src/shared/util/css/styles.css.

Importing CSS styles#

Import the stylesheet once from the consuming application’s entry point (e.g. main.tsx):

import './shared/util/css/styles.css';

By default, the rules in styles.css compose utility classes from Curity CSS Library (imported at the top of the file) using PostCSS @extend — e.g. .haapi-stepper-button { @extend .button, .button-medium, .button-primary, .w100, .mt2; }. The components themselves only know about the .haapi-stepper-* class names, so consumers are free to back those classes with anything they like.

Overriding or extending the defaults#

Because the components emit static class names, consumers can:

• Override / Extend: define rules for the same class names — or append additional CSS — in a separate stylesheet imported after styles.css.
• Replace: skip the default import entirely and provide your own definitions for the classes listed below — written in plain CSS, or composed from any third-party library, for example Tailwind CSS.

The Curity utility composition shown above is just how this project chose to implement the defaults; it is not a contract. Nothing in the components requires @curity/ui-kit-css, PostCSS, or @extend.

Customize with render interceptors#

Render interceptors are the programmatic way to customize the default step UI elements — loader, error, step, actions (form, client operation, selector), links, messages, and form fields.

Each is a function that receives the HaapiStepper API data for the target UI element (currentStep, loading, error, nextStep…) and returns either a React element to replace the default UI element, the API data to render the default UI element, or null to skip the element from being rendered:

💡 Design pattern note: always return or pass through the API data.

• To override: return your custom element.
• To delegate to the default renderer: return the API data ({ currentStep, history, loading, error, nextStep }), optionally modified.
• To remove an element: return null.

Customize with UI composition#

The declarative path to build UIs from scratch. Use it for what the API doesn’t expose as elements — grouping (fieldsets/tabs), cross-element layouts, inserting your own elements, and behaviour customizations (tabs, multi-step wizards). Best for layout and complex customizations.

Each HAAPI entity has a corresponding UI component (HaapiStepperActionsUI, HaapiStepperMessagesUI, HaapiStepperLinksUI…). HaapiStepper still runs the flow:

Mixed — combine the default with your own UI#

Render interceptors and UI composition aren’t exclusive — mix them wherever it helps. For example, return UI building blocks from a render interceptor to restructure part of the default UI while keeping everything else: a form render interceptor that re-lays-out the same fields, a step interceptor that swaps one step’s UI, or the headless HaapiStepper driving a mix of building blocks, plain HTML and third-party components.