API Reference
Complete reference for screen configuration and supported components.
Screen Configuration
The widget renders screens based on the Auth0 Forms API schema:
typescript
interface UIScreen {
title?: string;
description?: string;
components: UIComponent[];
messages?: Message[];
branding?: Branding;
theme?: string;
}
interface UIComponent {
component: string; // e.g., 'text-input', 'submit-button', 'social-button-group'
id: string;
label?: string;
[key: string]: any; // Component-specific props
}Supported Components
The widget supports 27+ Auth0 component types:
heading- Page headingsdescription- Descriptive texttext-input- Text, email, phone inputspassword-input- Password field with show/hidecheckbox-input- Checkboxesselect-input- Dropdown selectssubmit-button- Primary action buttonsbutton- Secondary action buttonssocial-button-group- Social login buttonsanchor- Links and navigationseparator- Visual dividersimage- Logos and images- And more...
Best Practices
Security
- Always validate user input on the server
- Use HTTPS for all API requests
- Implement CSRF protection for hosted pages
- Never expose sensitive data in screen configurations
- Validate the
stateparameter to prevent session fixation
Performance
- Use SSR for hosted pages to improve initial load time
- Lazy load the widget in SPAs if not immediately needed
- Cache branding and theme configurations
- Minimize screen transitions by combining related inputs
User Experience
- Provide clear error messages from the server
- Show loading states during submissions
- Preserve form data when navigating between screens
- Support browser back/forward navigation
- Use appropriate
autocompleteattributes
Development
- Use the event-based pattern for better testability
- Handle errors gracefully and show user-friendly messages
- Log events for debugging and analytics
- Test with different screen configurations
- Validate screen schemas on the server
Troubleshooting
Widget Not Rendering
- Check that the script is loaded:
<script type="module" src="/widget/authhero-widget.esm.js"></script> - Verify the
screenprop is valid JSON - Check browser console for errors
- Ensure the widget is a child of
<body>or a rendered element
Form Not Submitting
- Verify
formSubmitevent listener is attached - Check network tab for failed API requests
- Ensure the
stateparameter is valid and not expired - Verify CORS settings if calling from a different domain
Branding Not Applied
- Check that
brandingprop is valid JSON - Verify image URLs are accessible
- Check CSS custom properties are not being overridden
- Inspect element to see computed styles
Examples
See Integration Patterns for complete working examples of every integration pattern.
Further Reading
- Universal Login Flows - Complete flow documentation
- Auth0 Forms API - Forms API reference
- StencilJS Documentation - Web component framework