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.

:root_class - CSS class for the root div element.
:strategy_class - CSS class for a div surrounding each strategy component.
:show_banner - Whether or not to show the banner.
: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.

`AshAuthentication.Phoenix.Components.Password`

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

:root_class - CSS class for the root div element.
:slot_class - CSS class for the div surrounding the slot.
:interstitial_class - CSS class for the div element between the form and the button.
:toggler_class - CSS class for the toggler a element.
:sign_in_toggle_text - Toggle text to display when the sign in form is not showing (or nil to disable).
: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).
: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.
:hide_class - CSS class to apply to hide an element.

`AshAuthentication.Phoenix.Components.Password.RegisterForm`

Generates a default registration form.

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

`AshAuthentication.Phoenix.Components.Password.SignInForm`

Generates a default sign in form.

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

Password Reset

`AshAuthentication.Phoenix.ResetLive`

A generic, white-label password reset page.

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

`AshAuthentication.Phoenix.Components.Reset`

Renders a password-reset form.

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

`AshAuthentication.Phoenix.Components.Reset.Form`

Generates a default password reset form.

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

`AshAuthentication.Phoenix.Components.Password.ResetForm`

Generates a default password reset form.

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

Password

`AshAuthentication.Phoenix.Components.Password.Input`

Function components for dealing with form input during password authentication.

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

Magic Link

`AshAuthentication.Phoenix.Components.MagicLink`

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

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

OAuth2

`AshAuthentication.Phoenix.Components.Apple`

Generates a sign-in button for Apple.

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

`AshAuthentication.Phoenix.Components.OAuth2`

Generates a sign-in button for OAuth2.

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

Miscellaneous

`AshAuthentication.Phoenix.Components.HorizontalRule`

A horizontal rule with text.

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

`AshAuthentication.Phoenix.Components.Banner`

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

:text - Banner text. Set to nil to disable.
:root_class - CSS class for the root div element.
: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.
:dark_image_class - Css class for the img tag in dark mode.
:image_url - A URL for the img src attribute. Set to nil to disable.
:dark_image_url - A URL for the img src attribute in dark mode. Set to nil to disable.
:text_class - CSS class for the text div.

← Previous Page LiveView Routes