Troubleshooting

Nothing appears

isOpen defaults to false. Pass isOpen={true} and check appearanceDelay. Confirm the banner is not inside a clipped or transformed ancestor.

The banner is unstyled

Import @peax/consent-banner-theme/styles.css once in the application entry. The React JavaScript entry intentionally does not import CSS.

Accept or Apply does not close

Decision messages are requests. Handle them in onMsg, commit the decision and update isOpen to false.

Reopened preferences lose their values

Save the applied map in the application and pass its values back through preferencesContent[id].checked. The banner's internal draft is temporary.

The floating button does not open or close preferences

Handle navigation messages whose source is floating-button: set isOpen to true for on_open_preferences and false for on_close_preferences. The floating button requests these changes; the application controls visibility.

A custom category does not appear

Include the ID in preferencesSections. A preferencesContent override alone does not add a section. Update Accept and Reject maps for your chosen IDs.

Light mode gives a dark banner

Theme names describe the host page. Default banner colors contrast with that host; see styling.

Hydration warnings

Use matching initial locale, choices and visibility on the server and client. Restore browser-only storage after mounting before initializing the wrapper. Keep hooks and event callbacks behind a client component boundary.

Overrides do not win

Check cascade order and override public --pxc-* tokens on the correct .pxc element. Do not depend on private variables or internal markup selectors.

Newer examples do not typecheck

These docs target 0.2.0. Development-branch examples may use features or event fields introduced later. Use the generated public reference as the release-specific contract.