View Source Overriding Ash Authentication Phoenix's default UI

Ash Authentication Phoenix provides a default UI implementation to get you started, however we wanted there to be a middle road between "you gets what you gets" and "¯\(ツ)/¯ make your own". Thus AAP's system of UI overrides were born.

Each of our LiveView components has a number of hooks where you can override either the CSS styles, text or images.

Defining Overrides

You override these components by defining an "overrides module", which you will then provide in your router when setting up your routes.

For example, if we wanted to change the default banner used on the sign-in page:

defmodule MyAppWeb.AuthOverrides do
  use AshAuthentication.Phoenix.Overrides

  # Override a property per component
  override AshAuthentication.Phoenix.Components.Banner do
    # include any number of properties you want to override
    set :image_url, "/images/rickroll.gif"
  end
end

You only need to define the overrides you want to change. Unspecified overrides will use their default value.

Telling AshAuthentication about your overrides

To do this, you modify your sign_in_route calls to contain the overrides option. Be sure to put the AshAuthentication.Phoenix.Overrides.Default override last, as it contains the default values for all components!

defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  use AshAuthentication.Phoenix.Router

  # ...

  scope "/", MyAppWeb do
    sign_in_route(overrides: [MyAppWeb.AuthOverrides, AshAuthentication.Phoenix.Overrides.Default])
  end
end

Reference

The below documentation is autogenerated from the components that support overrides. All available overrides are listed here. If you are looking to override something not in this list, please open an issue, or even better a PR!

Looking at the source of the components can be enlightening to see exactly how an override is used. If you click on the name of component you are interested in, and then look in the top right (if you are on hexdocs), you will see a </> button that will take you to the source for that component. In that code, look for calls to override_for/3 to see specifically how each override is used.

`AshAuthentication.Phoenix.SignInLive`

A generic, white-label sign-in page.

:root_class - CSS class for the root div element.
:sign_in_id - Element ID for the SignIn LiveComponent.

Renders sign in mark-up for an authenticated resource.

:authentication_error_container_class - CSS class for the container for the text of the authentication error.
:authentication_error_text_class - CSS class for the authentication error text.
:root_class - CSS class for the root div element.
:show_banner - Whether or not to show the banner.
:strategy_class - CSS class for a div surrounding each strategy component.

`AshAuthentication.Phoenix.Components.Password`

Generates sign in, registration and reset forms for a resource.

:hide_class - CSS class to apply to hide an element.
:interstitial_class - CSS class for the div element between the form and the button.
:register_toggle_text - Toggle text to display when the register form is not showing (or nil to disable).
:reset_toggle_text - Toggle text to display when the reset form is not showing (or nil to disable).
:root_class - CSS class for the root div element.
:show_first - The form to show on first load. Either :sign_in or :register. Only relevant if paths aren't set for them in the router.
:sign_in_toggle_text - Toggle text to display when the sign in form is not showing (or nil to disable).
:slot_class - CSS class for the div surrounding the slot.
:toggler_class - CSS class for the toggler a element.

`AshAuthentication.Phoenix.Components.Password.RegisterForm`

Generates a default registration form.

:disable_button_text - Text for the submit button when the request is happening.
:form_class - CSS class for the form element.
:label_class - CSS class for the h2 element.
:root_class - CSS class for the root div element.
:slot_class - CSS class for the div surrounding the slot.

`AshAuthentication.Phoenix.Components.Password.SignInForm`

Generates a default sign in form.

:disable_button_text - Text for the submit button when the request is happening.
:form_class - CSS class for the form element.
:label_class - CSS class for the h2 element.
:root_class - CSS class for the root div element.
:slot_class - CSS class for the div surrounding the slot.

Password Reset

`AshAuthentication.Phoenix.ResetLive`

A generic, white-label password reset page.

:reset_id - Element ID for the Reset LiveComponent.
:root_class - CSS class for the root div element.

`AshAuthentication.Phoenix.Components.Reset`

Renders a password-reset form.

:root_class - CSS class for the root div element.
:show_banner - Whether or not to show the banner.
:strategy_class - CSS class for a div surrounding each strategy component.

`AshAuthentication.Phoenix.Components.Reset.Form`

Generates a default password reset form.

:disable_button_text - Text for the submit button when the request is happening.
:form_class - CSS class for the form element.
:label_class - CSS class for the h2 element.
:root_class - CSS class for the root div element.
:spacer_class - CSS classes for space between the password input and submit elements.

`AshAuthentication.Phoenix.Components.Password.ResetForm`

Generates a default password reset form.

:disable_button_text - Text for the submit button when the request is happening.
:form_class - CSS class for the form element.
:label_class - CSS class for the h2 element.
:reset_flash_text - Text for the flash message when a request is received. Set to nil to disable.
:root_class - CSS class for the root div element.
:slot_class - CSS class for the div surrounding the slot.

Password

`AshAuthentication.Phoenix.Components.Password.Input`

Function components for dealing with form input during password authentication.

:error_li - CSS class for the li elements on error lists.
:error_ul - CSS class for the ul element on error lists.
:field_class - CSS class for div elements surrounding the fields.
:identity_input_label - Label for identity field.
:identity_input_placeholder - Placeholder for identity field.
:input_class - CSS class for text/password input elements.
:input_class_with_error - CSS class for text/password input elements when there is a validation error.
:input_debounce - Number of milliseconds to debounce input by (or nil to disable).
:label_class - CSS class for label elements.
:password_confirmation_input_label - Label for password confirmation field.
:password_input_label - Label for password field.
:submit_class - CSS class for the form submit input element.

Magic Link

`AshAuthentication.Phoenix.Components.MagicLink`

Generates a sign-in for for a resource using the "Magic link" strategy.

:disable_button_text - Text for the submit button when the request is happening.
:form_class - CSS class for the form element.
:label_class - CSS class for the h2 element.
:request_flash_text - Text for the flash message when a request is received. Set to nil to disable.
:root_class - CSS class for the root div element.

OAuth2

`AshAuthentication.Phoenix.Components.Apple`

Generates a sign-in button for Apple.

:icon_class - CSS classes for the icon SVG.
:link_class - CSS classes for the a element.
:root_class - CSS classes for the root div element.

`AshAuthentication.Phoenix.Components.OAuth2`

Generates a sign-in button for OAuth2.

:icon_class - CSS classes for the icon SVG.
:link_class - CSS classes for the a element.
:root_class - CSS classes for the root div element.

Miscellaneous

`AshAuthentication.Phoenix.Components.HorizontalRule`

A horizontal rule with text.

:hr_inner_class - CSS class for the inner div element of the horizontal rule.
:hr_outer_class - CSS class for the outer div element of the horizontal rule.
:root_class - CSS class for the root div element.
:text - Text to display in front of the horizontal rule.
:text_inner_class - CSS class for the inner div element of the text area.
:text_outer_class - CSS class for the outer div element of the text area.

`AshAuthentication.Phoenix.Components.Banner`

Renders a very simple banner at the top of the sign-in component.

:dark_image_class - Css class for the img tag in dark mode.
:dark_image_url - A URL for the img src attribute in dark mode. Set to nil to disable.
:href_class - CSS class for the a tag.
:href_url - A URL for the banner image to link to. Set to nil to disable.
:image_class - CSS class for the img tag.
:image_url - A URL for the img src attribute. Set to nil to disable.
:root_class - CSS class for the root div element.
:text - Banner text. Set to nil to disable.
:text_class - CSS class for the text div.

← Previous Page LiveView Routes