ACUL screens flash on transition

We’ve implemented customized branded ACUL screens and can login successfully on multiple browsers, devices, and screen sizes. Core functionality is fine, however we’ve noticed two major issues which are blockers for us.

First, when using ACUL screens we’ve noticed notable flashes when transitioning between pages to the default background colour set in the auth0 dashboard for the tenant. This problem is exacerbated on slow speeds, but even on gigabit connections the flash is visible. We’re not making any network calls other than for lazy loaded logos - all customization is done in the ULThemePageLayout component via untrustedData?.authorizationParams. Tests are done with browser caching turned on and all links from the Head Tags section have already been fetched. In the worst case, this can result in blank screens for five or ten seconds at a time.

Secondly, we’ve noticed that the passkey-enrollment page does not properly pass authorizationParams. This object comes back nil on this specific page when all other pages within the login flow get the values correctly. This page is configured identically to others through the CLI, and the dashboard shows all of our custom parameters listed and enabled under Additional Data for the page.

import { useCurrentScreen } from "@auth0/auth0-acul-react";

const screen = useCurrentScreen();
const authorizationParams = screen?.untrustedData?.authorizationParams;
// authorizationParams is null/undefined ONLY on passkey-enrollment

Hi @lp_engineering,

Welcome to the Auth0 Community!

Please allow me some time to look into this and I will come back with an answer as soon as possibe.

Thank you!
Best regards,
Remus

Remus, Thank you for taking a look into this for my team. We are on a tight schedule to get this integration out to production, so if there are any initial thoughts or things to try that you can think of, we are all ears.

Hi @lp_engineering and @qwade,

Welcome to the Auth0 Community!

Thank you for your patience, as I completely understand that this is an urgent matter so allow me to share a few findings, although I believe the current news aren’t specifically great.

I have reviewed the screen flashing issue you’re encountering and the behavior you’re observing is often referred to as a “Flash of Unstyled Content”. The engine that renders your custom screens needs a moment to process your code and styles, especially for custom parameters you are sending to the SDK. From similar previous cases, our Engineering team has mentioned that this issue are likely to be caused by a momentary delay as the browser loads your custom pages, the specific caching behavior of the browser, or potential slow/delayed JS custom JavaScript within your code. This is sometimes more noticeable in certain environments, such as on slower networks or within embedded browser views, which is why a precise diagnosis is usually needed.

If the flash shows your default tenant’s background color, it strongly indicates that the browser is correctly rendering the base page before your custom ACUL theme has finished loading. A quick workaround that I could think of would be to ensure the page’s initial color matches your custom theme’s color. You can use the Auth0 Deploy CLI to update your tenant’s branding settings, setting the primary_background_color to the exact same color value used in your ACUL page layout, so that the “flash” becomes invisible to end users.

However, if you are seeing a blank white screen, it could imply a more complex browser-level issue, in which case a deeper investigation might be needed, as a simple configuration change would be unlikely to solve it. Since I have seen you have already opened a support ticket, I would recommend updating the information on that case regarding whether the flash you see is your background color or a blank white page and the type of application being used, since for further troubleshooting a HAR file might be needed or exact proof of reproducible steps, so that you can receive a direct response from our Engineering team.

Regarding your 2nd question about authorizationParams on the passkey-enrollment screen, you are also correct. The behavior you are seeing where authorizationParams is nil or undefined on the passkey-enrollment screen is expected, though we understand it is a significant blocker.

Auth0’s feature for passing custom parameters to Universal Login screens is currently only supported for a specific list of screens (like login and signup) and passkey-enrollment is unfortunately not on that list yet. I can definitely understand why the documentation can be confusing at the moment, as this is a current known limitation of the ACUL SDK.

Since you can not rely on custom parameters for the passkey-enrollment screen, the workaround would be to customize this screen within your existing ACUL project without them by only using static elements.

Use the useCurrentScreen hook to identify when the passkey-enrollment screen is active and apply specific styling or logic. You are already doing this to check for the params, so you can extend this logic to apply your UI. You can consider importing and bundling assets directly with your ACUL application so they can be referenced with a static path. We recognize that this is not as dynamic as using authorizationParams , but it should allow you to achieve a branded UI on the passkey-enrollment screen as well while staying within the ACUL framework.

I hope this helps and if you have further inquiries on the matter please let me know!
Best regards,
Remus

Remus, thank you for your assistance and thoughtful/thorough response. I have asked the engineer who has been working on the custom branding to read through your recommendations and we will respond once we have a plan pulled together.