music_library/AGENTS.md

Project architecture

Project architecture

phoenix:ecto usage

Ecto Guidelines

• Always preload Ecto associations in queries when they'll be accessed in templates, ie a message that needs to reference the message.user.email
• Remember import Ecto.Query and other supporting modules when you write seeds.exs
• Ecto.Schema fields always use the :string type, even for :text, columns, ie: field :name, :string
• Ecto.Changeset.validate_number/2 DOES NOT SUPPORT the :allow_nil option. By default, Ecto validations only run if a change for the given field exists and the change value is not nil, so such as option is never needed
• You must use Ecto.Changeset.get_field(changeset, :field) to access changeset fields
• Fields which are set programatically, such as user_id, must not be listed in cast calls or similar for security purposes. Instead they must be explicitly set when creating the struct
• Always invoke mix ecto.gen.migration migration_name_using_underscores when generating migration files, so the correct timestamp and conventions are applied

phoenix:elixir usage

Elixir guidelines

• Elixir lists do not support index based access via the access syntax

  Never do this (invalid):

  i = 0
  mylist = ["blue", "green"]
  mylist[i]
  

  Instead, always use Enum.at, pattern matching, or List for index based list access, ie:

  i = 0
  mylist = ["blue", "green"]
  Enum.at(mylist, i)
  

• Elixir variables are immutable, but can be rebound, so for block expressions like if, case, cond, etc you must bind the result of the expression to a variable if you want to use it and you CANNOT rebind the result inside the expression, ie:

  # INVALID: we are rebinding inside the `if` and the result never gets assigned
  if connected?(socket) do
    socket = assign(socket, :val, val)
  end
  
  # VALID: we rebind the result of the `if` to a new variable
  socket =
    if connected?(socket) do
      assign(socket, :val, val)
    end
  

• Never nest multiple modules in the same file as it can cause cyclic dependencies and compilation errors

• Never use map access syntax (changeset[:field]) on structs as they do not implement the Access behaviour by default. For regular structs, you must access the fields directly, such as my_struct.field or use higher level APIs that are available on the struct if they exist, Ecto.Changeset.get_field/2 for changesets

• Elixir's standard library has everything necessary for date and time manipulation. Familiarize yourself with the common Time, Date, DateTime, and Calendar interfaces by accessing their documentation as necessary. Never install additional dependencies unless asked or for date/time parsing (which you can use the date_time_parser package)

• Don't use String.to_atom/1 on user input (memory leak risk)

• Predicate function names should not start with is_ and should end in a question mark. Names like is_thing should be reserved for guards

• Elixir's builtin OTP primitives like DynamicSupervisor and Registry, require names in the child spec, such as {DynamicSupervisor, name: MyApp.MyDynamicSup}, then you can use DynamicSupervisor.start_child(MyApp.MyDynamicSup, child_spec)

• Use Task.async_stream(collection, callback, options) for concurrent enumeration with back-pressure. The majority of times you will want to pass timeout: :infinity as option

Mix guidelines

• Read the docs and options before using tasks (by using mix help task_name)
• To debug test failures, run tests in a specific file with mix test test/my_test.exs or run all previously failed tests with mix test --failed
• mix deps.clean --all is almost never needed. Avoid using it unless you have good reason

Test guidelines

• Always use start_supervised!/1 to start processes in tests as it guarantees cleanup between tests
• Avoid Process.sleep/1 and Process.alive?/1 in tests

  • Instead of sleeping to wait for a process to finish, always use Process.monitor/1 and assert on the DOWN message:

    ref = Process.monitor(pid) assert_receive {:DOWN, ^ref, :process, ^pid, :normal}

  • Instead of sleeping to synchronize before the next call, always use _ = :sys.get_state/1 to ensure the process has handled prior messages

phoenix:html usage

Phoenix HTML guidelines

• Phoenix templates always use ~H or .html.heex files (known as HEEx), never use ~E

• Always use the imported Phoenix.Component.form/1 and Phoenix.Component.inputs_for/1 function to build forms. Never use Phoenix.HTML.form_for or Phoenix.HTML.inputs_for as they are outdated

• When building forms always use the already imported Phoenix.Component.to_form/2 (assign(socket, form: to_form(...)) and <.form for={@form} id="msg-form">), then access those forms in the template via @form[:field]

• Always add unique DOM IDs to key elements (like forms, buttons, etc) when writing templates, these IDs can later be used in tests (<.form for={@form} id="product-form">)

• For "app wide" template imports, you can import/alias into the my_app_web.ex's html_helpers block, so they will be available to all LiveViews, LiveComponent's, and all modules that do use MyAppWeb, :html (replace "my_app" by the actual app name)

• Elixir supports if/else but does NOT support if/else if or if/elsif. Never use else if or elseif in Elixir, always use cond or case for multiple conditionals.

  Never do this (invalid):

  <%= if condition do %>
    ...
  <% else if other_condition %>
    ...
  <% end %>
  

  Instead always do this:

  <%= cond do %>
    <% condition -> %>
      ...
    <% condition2 -> %>
      ...
    <% true -> %>
      ...
  <% end %>
  

• HEEx require special tag annotation if you want to insert literal curly's like { or }. If you want to show a textual code snippet on the page in a <pre> or <code> block you must annotate the parent tag with phx-no-curly-interpolation:

  <code phx-no-curly-interpolation>
    let obj = {key: "val"}
  </code>
  

  Within phx-no-curly-interpolation annotated tags, you can use { and } without escaping them, and dynamic Elixir expressions can still be used with <%= ... %> syntax

• HEEx class attrs support lists, but you must always use list [...] syntax. You can use the class list syntax to conditionally add classes, always do this for multiple class values:

  <a class={[
    "px-2 text-white",
    @some_flag && "py-5",
    if(@other_condition, do: "border-red-500", else: "border-blue-100"),
    ...
  ]}>Text</a>
  

  and always wrap if's inside {...} expressions with parens, like done above (if(@other_condition, do: "...", else: "..."))

  and never do this, since it's invalid (note the missing [ and ]):

  <a class={
    "px-2 text-white",
    @some_flag && "py-5"
  }> ...
  => Raises compile syntax error on invalid HEEx attr syntax
  

• Never use <% Enum.each %> or non-for comprehensions for generating template content, instead always use <%= for item <- @collection do %>

• HEEx HTML comments use <%!-- comment --%>. Always use the HEEx HTML comment syntax for template comments (<%!-- comment --%>)

• HEEx allows interpolation via {...} and <%= ... %>, but the <%= %> only works within tag bodies. Always use the {...} syntax for interpolation within tag attributes, and for interpolation of values within tag bodies. Always interpolate block constructs (if, cond, case, for) within tag bodies using <%= ... %>.

  Always do this:

  <div id={@id}>
    {@my_assign}
    <%= if @some_block_condition do %>
      {@another_assign}
    <% end %>
  </div>
  

  and Never do this – the program will terminate with a syntax error:

  <%!-- THIS IS INVALID NEVER EVER DO THIS --%>
  <div id="<%= @invalid_interpolation %>">
    {if @invalid_block_construct do}
    {end}
  </div>
  

phoenix:liveview usage

Phoenix LiveView guidelines

• Never use the deprecated live_redirect and live_patch functions, instead always use the <.link navigate={href}> and <.link patch={href}> in templates, and push_navigate and push_patch functions LiveViews
• Avoid LiveComponent's unless you have a strong, specific need for them
• LiveViews should be named like AppWeb.WeatherLive, with a Live suffix. When you go to add LiveView routes to the router, the default :browser scope is already aliased with the AppWeb module, so you can just do live "/weather", WeatherLive

LiveView streams

• Always use LiveView streams for collections for assigning regular lists to avoid memory ballooning and runtime termination with the following operations:

  • basic append of N items - stream(socket, :messages, [new_msg])
  • resetting stream with new items - stream(socket, :messages, [new_msg], reset: true) (e.g. for filtering items)
  • prepend to stream - stream(socket, :messages, [new_msg], at: -1)
  • deleting items - stream_delete(socket, :messages, msg)

• When using the stream/3 interfaces in the LiveView, the LiveView template must 1) always set phx-update="stream" on the parent element, with a DOM id on the parent element like id="messages" and 2) consume the @streams.stream_name collection and use the id as the DOM id for each child. For a call like stream(socket, :messages, [new_msg]) in the LiveView, the template would be:

  <div id="messages" phx-update="stream">
    <div :for={{id, msg} <- @streams.messages} id={id}>
      {msg.text}
    </div>
  </div>
  

• LiveView streams are not enumerable, so you cannot use Enum.filter/2 or Enum.reject/2 on them. Instead, if you want to filter, prune, or refresh a list of items on the UI, you must refetch the data and re-stream the entire stream collection, passing reset: true:

  def handle_event("filter", %{"filter" => filter}, socket) do
    # re-fetch the messages based on the filter
    messages = list_messages(filter)
  
    {:noreply,
     socket
     |> assign(:messages_empty?, messages == [])
     # reset the stream with the new messages
     |> stream(:messages, messages, reset: true)}
  end
  

• LiveView streams do not support counting or empty states. If you need to display a count, you must track it using a separate assign. For empty states, you can use Tailwind classes:

  <div id="tasks" phx-update="stream">
    <div class="hidden only:block">No tasks yet</div>
    <div :for={{id, task} <- @stream.tasks} id={id}>
      {task.name}
    </div>
  </div>
  

  The above only works if the empty state is the only HTML block alongside the stream for-comprehension.

• When updating an assign that should change content inside any streamed item(s), you MUST re-stream the items along with the updated assign:

  def handle_event("edit_message", %{"message_id" => message_id}, socket) do
    message = Chat.get_message!(message_id)
    edit_form = to_form(Chat.change_message(message, %{content: message.content}))
  
    # re-insert message so @editing_message_id toggle logic takes effect for that stream item
    {:noreply,
     socket
     |> stream_insert(:messages, message)
     |> assign(:editing_message_id, String.to_integer(message_id))
     |> assign(:edit_form, edit_form)}
  end
  

  And in the template:

  <div id="messages" phx-update="stream">
    <div :for={{id, message} <- @streams.messages} id={id} class="flex group">
      {message.username}
      <%= if @editing_message_id == message.id do %>
        <%!-- Edit mode --%>
        <.form for={@edit_form} id="edit-form-#{message.id}" phx-submit="save_edit">
          ...
        </.form>
      <% end %>
    </div>
  </div>
  

• Never use the deprecated phx-update="append" or phx-update="prepend" for collections

LiveView JavaScript interop

• Remember anytime you use phx-hook="MyHook" and that JS hook manages its own DOM, you must also set the phx-update="ignore" attribute
• Always provide an unique DOM id alongside phx-hook otherwise a compiler error will be raised

LiveView hooks come in two flavors, 1) colocated js hooks for "inline" scripts defined inside HEEx, and 2) external phx-hook annotations where JavaScript object literals are defined and passed to the LiveSocket constructor.

Inline colocated js hooks

Never write raw embedded <script> tags in heex as they are incompatible with LiveView. Instead, always use a colocated js hook script tag (:type={Phoenix.LiveView.ColocatedHook}) when writing scripts inside the template:

<input type="text" name="user[phone_number]" id="user-phone-number" phx-hook=".PhoneNumber" />
<script :type={Phoenix.LiveView.ColocatedHook} name=".PhoneNumber">
  export default {
    mounted() {
      this.el.addEventListener("input", e => {
        let match = this.el.value.replace(/\D/g, "").match(/^(\d{3})(\d{3})(\d{4})$/)
        if(match) {
          this.el.value = `${match[1]}-${match[2]}-${match[3]}`
        }
      })
    }
  }
</script>

• colocated hooks are automatically integrated into the app.js bundle
• colocated hooks names MUST ALWAYS start with a . prefix, i.e. .PhoneNumber

External phx-hook

External JS hooks (<div id="myhook" phx-hook="MyHook">) must be placed in assets/js/ and passed to the LiveSocket constructor:

const MyHook = {
  mounted() { ... }
}
let liveSocket = new LiveSocket("/live", Socket, {
  hooks: { MyHook }
});

Pushing events between client and server

Use LiveView's push_event/3 when you need to push events/data to the client for a phx-hook to handle. Always return or rebind the socket on push_event/3 when pushing events:

# re-bind socket so we maintain event state to be pushed
socket = push_event(socket, "my_event", %{...})

# or return the modified socket directly:
def handle_event("some_event", _, socket) do
  {:noreply, push_event(socket, "my_event", %{...})}
end

Pushed events can then be picked up in a JS hook with this.handleEvent:

mounted() {
  this.handleEvent("my_event", data => console.log("from server:", data));
}

Clients can also push an event to the server and receive a reply with this.pushEvent:

mounted() {
  this.el.addEventListener("click", e => {
    this.pushEvent("my_event", { one: 1 }, reply => console.log("got reply from server:", reply));
  })
}

Where the server handled it via:

def handle_event("my_event", %{"one" => 1}, socket) do
  {:reply, %{two: 2}, socket}
end

LiveView tests

• Phoenix.LiveViewTest module and LazyHTML (included) for making your assertions

• Form tests are driven by Phoenix.LiveViewTest's render_submit/2 and render_change/2 functions

• Come up with a step-by-step test plan that splits major test cases into small, isolated files. You may start with simpler tests that verify content exists, gradually add interaction tests

• Always reference the key element IDs you added in the LiveView templates in your tests for Phoenix.LiveViewTest functions like element/2, has_element/2, selectors, etc

• Never tests again raw HTML, always use element/2, has_element/2, and similar: assert has_element?(view, "#my-form")

• Instead of relying on testing text content, which can change, favor testing for the presence of key elements

• Focus on testing outcomes rather than implementation details

• Be aware that Phoenix.Component functions like <.form> might produce different HTML than expected. Test against the output HTML structure, not your mental model of what you expect it to be

• When facing test failures with element selectors, add debug statements to print the actual HTML, but use LazyHTML selectors to limit the output, ie:

  html = render(view)
  document = LazyHTML.from_fragment(html)
  matches = LazyHTML.filter(document, "your-complex-selector")
  IO.inspect(matches, label: "Matches")
  

Form handling

Creating a form from params

If you want to create a form based on handle_event params:

def handle_event("submitted", params, socket) do
  {:noreply, assign(socket, form: to_form(params))}
end

When you pass a map to to_form/1, it assumes said map contains the form params, which are expected to have string keys.

You can also specify a name to nest the params:

def handle_event("submitted", %{"user" => user_params}, socket) do
  {:noreply, assign(socket, form: to_form(user_params, as: :user))}
end

Creating a form from changesets

When using changesets, the underlying data, form params, and errors are retrieved from it. The :as option is automatically computed too. E.g. if you have a user schema:

defmodule MyApp.Users.User do
  use Ecto.Schema
  ...
end

And then you create a changeset that you pass to to_form:

%MyApp.Users.User{}
|> Ecto.Changeset.change()
|> to_form()

Once the form is submitted, the params will be available under %{"user" => user_params}.

In the template, the form form assign can be passed to the <.form> function component:

<.form for={@form} id="todo-form" phx-change="validate" phx-submit="save">
  <.input field={@form[:field]} type="text" />
</.form>

Always give the form an explicit, unique DOM ID, like id="todo-form".

Avoiding form errors

Always use a form assigned via to_form/2 in the LiveView, and the <.input> component in the template. In the template always access forms this:

<%!-- ALWAYS do this (valid) --%>
<.form for={@form} id="my-form">
  <.input field={@form[:field]} type="text" />
</.form>

And never do this:

<%!-- NEVER do this (invalid) --%>
<.form for={@changeset} id="my-form">
  <.input field={@changeset[:field]} type="text" />
</.form>

• You are FORBIDDEN from accessing the changeset in the template as it will cause errors
• Never use <.form let={f} ...> in the template, instead always use <.form for={@form} ...>, then drive all form references from the form assign as in @form[:field]. The UI should always be driven by a to_form/2 assigned in the LiveView module that is derived from a changeset

phoenix:phoenix usage

Phoenix guidelines

• Remember Phoenix router scope blocks include an optional alias which is prefixed for all routes within the scope. Always be mindful of this when creating routes within a scope to avoid duplicate module prefixes.

• You never need to create your own alias for route definitions! The scope provides the alias, ie:

  scope "/admin", AppWeb.Admin do
    pipe_through :browser
  
    live "/users", UserLive, :index
  end
  

  the UserLive route would point to the AppWeb.Admin.UserLive module

• Phoenix.View no longer is needed or included with Phoenix, don't use it

usage_rules usage

A config-driven dev tool for Elixir projects to manage AGENTS.md files and agent skills from dependencies

Using Usage Rules

Many packages have usage rules, which you should thoroughly consult before taking any action. These usage rules contain guidelines and rules directly from the package authors. They are your best source of knowledge for making decisions.

Modules & functions in the current app and dependencies

When looking for docs for modules & functions that are dependencies of the current project, or for Elixir itself, use mix usage_rules.docs

# Search a whole module
mix usage_rules.docs Enum

# Search a specific function
mix usage_rules.docs Enum.zip

# Search a specific function & arity
mix usage_rules.docs Enum.zip/1

Searching Documentation

You should also consult the documentation of any tools you are using, early and often. The best way to accomplish this is to use the usage_rules.search_docs mix task. Once you have found what you are looking for, use the links in the search results to get more detail. For example:

# Search docs for all packages in the current application, including Elixir
mix usage_rules.search_docs Enum.zip

# Search docs for specific packages
mix usage_rules.search_docs Req.get -p req

# Search docs for multi-word queries
mix usage_rules.search_docs "making requests" -p req

# Search only in titles (useful for finding specific functions/modules)
mix usage_rules.search_docs "Enum.zip" --query-by title

usage_rules:elixir usage

Elixir Core Usage Rules

Pattern Matching

• Use pattern matching over conditional logic when possible
• Prefer to match on function heads instead of using if/else or case in function bodies
• %{} matches ANY map, not just empty maps. Use map_size(map) == 0 guard to check for truly empty maps

Error Handling

• Use {:ok, result} and {:error, reason} tuples for operations that can fail
• Avoid raising exceptions for control flow
• Use with for chaining operations that return {:ok, _} or {:error, _}

Common Mistakes to Avoid

• Elixir has no return statement, nor early returns. The last expression in a block is always returned.
• Don't use Enum functions on large collections when Stream is more appropriate
• Avoid nested case statements - refactor to a single case, with or separate functions
• Don't use String.to_atom/1 on user input (memory leak risk)
• Lists and enumerables cannot be indexed with brackets. Use pattern matching or Enum functions
• Prefer Enum functions like Enum.reduce over recursion
• When recursion is necessary, prefer to use pattern matching in function heads for base case detection
• Using the process dictionary is typically a sign of unidiomatic code
• Only use macros if explicitly requested
• There are many useful standard library functions, prefer to use them where possible

Function Design

• Use guard clauses: when is_binary(name) and byte_size(name) > 0
• Prefer multiple function clauses over complex conditional logic
• Name functions descriptively: calculate_total_price/2 not calc/2
• Predicate function names should not start with is and should end in a question mark.
• Names like is_thing should be reserved for guards

Data Structures

• Use structs over maps when the shape is known: defstruct [:name, :age]
• Prefer keyword lists for options: [timeout: 5000, retries: 3]
• Use maps for dynamic key-value data
• Prefer to prepend to lists [new | list] not list ++ [new]

Mix Tasks

• Use mix help to list available mix tasks
• Use mix help task_name to get docs for an individual task
• Read the docs and options fully before using tasks

Testing

• Run tests in a specific file with mix test test/my_test.exs and a specific test with the line number mix test path/to/test.exs:123
• Limit the number of failed tests with mix test --max-failures n
• Use @tag to tag specific tests, and mix test --only tag to run only those tests
• Use assert_raise for testing expected exceptions: assert_raise ArgumentError, fn -> invalid_function() end
• Use mix help test to for full documentation on running tests

Debugging

• Use dbg/1 to print values while debugging. This will display the formatted value and other relevant information in the console.

usage_rules:otp usage

OTP Usage Rules

GenServer Best Practices

• Keep state simple and serializable
• Handle all expected messages explicitly
• Use handle_continue/2 for post-init work
• Implement proper cleanup in terminate/2 when necessary

Process Communication

• Use GenServer.call/3 for synchronous requests expecting replies
• Use GenServer.cast/2 for fire-and-forget messages.
• When in doubt, use call over cast, to ensure back-pressure
• Set appropriate timeouts for call/3 operations

Fault Tolerance

• Set up processes such that they can handle crashing and being restarted by supervisors
• Use :max_restarts and :max_seconds to prevent restart loops

Task and Async

• Use Task.Supervisor for better fault tolerance
• Handle task failures with Task.yield/2 or Task.shutdown/2
• Set appropriate task timeouts
• Use Task.async_stream/3 for concurrent enumeration with back-pressure

fluxon usage

Fluxon UI Components

Fluxon UI Components Usage Rules

This document provides a guide for Large Language Models (LLMs) on how to use Fluxon UI components. It covers component attributes, slots, and provides usage examples for different scenarios.

Accordion

The Accordion component provides collapsible content sections with headers that toggle panel visibility.

Components

• accordion: Main container that manages state and accessibility
• accordion_item: Individual collapsible sections

Attributes

accordion

• id (string, optional): Unique identifier for the accordion container
• class (any, optional): Additional CSS classes for the accordion container
• multiple (boolean, default: false): Allow multiple items to be expanded simultaneously
• prevent_all_closed (boolean, default: false): Prevent all items from being closed at once
• animation_duration (integer, default: 300): Duration of expand/collapse animation in milliseconds
• rest: Additional HTML attributes

accordion_item

• id (string, optional): Unique identifier for the accordion item
• class (any, optional): Additional CSS classes for the accordion item container
• expanded (boolean, default: false): Initial expanded state of the item
• icon (boolean, default: true): Show/hide the chevron icon
• rest: Additional HTML attributes

Slots

accordion

• inner_block (required): Contains one or more accordion_item components

accordion_item

• header (required): Always-visible clickable area that toggles the panel
  • class (optional): Additional CSS classes for the header button
• panel (required): Expandable content area
  • class (optional): Additional CSS classes for the panel content

Usage Examples

Basic Accordion

<.accordion>
  <.accordion_item>
    <:header>What is Fluxon?</:header>
    <:panel>
      Fluxon is a powerful UI component library for Phoenix LiveView applications.
    </:panel>
  </.accordion_item>

  <.accordion_item>
    <:header>How do I get started?</:header>
    <:panel>
      Add Fluxon to your dependencies and follow the installation guide.
    </:panel>
  </.accordion_item>
</.accordion>

Multiple Sections and Rich Headers

<.accordion multiple>
  <.accordion_item>
    <:header class="flex items-center gap-3">
      <.icon name="document" class="size-5 text-zinc-400" />
      <div>
        <h3 class="font-medium">Documentation</h3>
        <p class="text-sm text-zinc-500">View the complete documentation</p>
      </div>
      <.badge class="ml-auto">New</.badge>
    </:header>
    <:panel>Detailed documentation content...</:panel>
  </.accordion_item>
</.accordion>

Custom Animation and No Icon

<.accordion animation_duration={500}>
  <.accordion_item icon={false}>
    <:header>Custom Header Without Chevron</:header>
    <:panel>No chevron icon is shown for this item</:panel>
  </.accordion_item>
</.accordion>

Alert

The Alert component displays status messages, notifications, and interactive feedback with various visual styles and interactive elements.

Attributes

• id (string, optional): Unique identifier for the alert element
• class (any, optional): Additional CSS classes for the alert element
• title (string, optional): Main heading text of the alert
• subtitle (string, optional): Secondary text displayed alongside the title
• color (string, default: "default"): Visual style color - "default", "primary", "danger", "success", "info", "warning"
• hide_icon (boolean, default: false): Hide the alert's status icon
• hide_close (boolean, default: false): Hide the alert's close button
• on_close (JS, default: %JS{}): LiveView JS commands to execute when closed

Slots

• inner_block (optional): Main content displayed in the alert body
• icon (optional): Custom icon to replace the default status icon

Usage Examples

Basic Alert with Colors

<.alert>Simple alert message</.alert>

<.alert color="info" title="Update Available">
  A new version of the application is ready to install.
</.alert>

<.alert color="success" title="Order Confirmed">
  Your order has been successfully processed.
</.alert>

<.alert color="warning" title="Session Expiring">
  Your session will expire in 5 minutes.
</.alert>

<.alert color="danger" title="Connection Lost">
  Unable to connect to the server.
</.alert>

Alert with Actions

<.alert
  color="warning"
  title="Unsaved Changes"
  on_close={JS.push("dismiss_warning")}>
  You have unsaved changes that will be lost.

  <div class="mt-4 flex space-x-2">
    <.button size="xs">Save Changes</.button>
    <.button size="xs" color="ghost">Discard</.button>
  </div>
</.alert>

Non-dismissible and Custom Icon

<.alert hide_close>
  This alert cannot be dismissed
</.alert>

<.alert>
  <:icon>
    <.icon name="hero-bell" class="size-5" />
  </:icon>
  Custom notification icon
</.alert>

Autocomplete

The Autocomplete component provides a text input that filters a list of options as the user types, with keyboard navigation and accessibility features. It supports both client-side and server-side search capabilities.

Attributes

• id (any, optional): Unique identifier for the autocomplete component
• name (any): Form name for the autocomplete (required when not using field)
• field (Phoenix.HTML.FormField, optional): Form field to bind to
• class (any, optional): Additional CSS classes for the field wrapper element
• label (string, optional): Primary label for the autocomplete
• sublabel (string, optional): Additional context displayed beside the main label
• help_text (string, optional): Help text displayed below the autocomplete
• description (string, optional): Description displayed below the label
• placeholder (string, optional): Text to display when input is empty
• autofocus (boolean, default: false): Whether input should have autofocus
• disabled (boolean, default: false): Disable the autocomplete component
• size (string, default: "md"): Size variant - "xs", "sm", "md", "lg", "xl"
• search_threshold (integer, default: 0): Minimum characters before showing suggestions
• no_results_text (string, default: "No results found for "%{query}"."): Text for no results
• on_search (string, optional): LiveView event name for server-side search
• debounce (integer, default: 200): Debounce time in milliseconds for server-side searches
• search_mode (string, default: "contains"): Search mode - "contains", "starts-with", "exact"
• open_on_focus (boolean, default: false): Open listbox when input is focused
• value (any, optional): Current selected value
• errors (list, default: []): List of error messages
• options (list, required): List of options in various formats
• clearable (boolean, default: false): Show clear button to remove selection
• rest: Additional HTML attributes

Slots

• inner_prefix (optional): Content inside input field before text
• outer_prefix (optional): Content outside and before input field
• inner_suffix (optional): Content inside input field after text
• outer_suffix (optional): Content outside and after input field
• option (optional): Custom option rendering slot
• empty_state (optional): Custom empty state rendering
• header (optional): Custom header content for listbox
• footer (optional): Custom footer content for listbox

Usage Examples

Basic and Form Integration

<.autocomplete
  name="country"
  options={[{"United States", "us"}, {"Canada", "ca"}]}
  placeholder="Search countries..."
/>

<.form :let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.autocomplete
    field={f[:user_id]}
    label="Assigned To"
    options={@users}
  />
</.form>

Different Option Formats

<!-- List of strings -->
<.autocomplete
  name="fruits"
  options={["Apple", "Banana", "Cherry"]}
  placeholder="Search fruits..."
/>

<!-- Grouped options -->
<.autocomplete
  name="products"
  options={[
    {"Fruits", [{"Apple", "apple"}, {"Banana", "banana"}]},
    {"Vegetables", [{"Carrot", "carrot"}, {"Broccoli", "broccoli"}]}
  ]}
  placeholder="Search products..."
/>

Size Variants and Labels

<.autocomplete name="sm" size="sm" placeholder="Small" options={@options} />
<.autocomplete name="lg" size="lg" placeholder="Large" options={@options} />

<.autocomplete
  name="language"
  label="Programming Language"
  sublabel="Required"
  description="Choose the web framework for your project"
  help_text="Choose from our supported platforms"
  placeholder="Select your favorite..."
  options={["Elixir", "Phoenix", "LiveView"]}
/>

Affixes and Search Features

<!-- With icon prefix -->
<.autocomplete name="user_search" options={@users} placeholder="Search users...">
  <:inner_prefix>
    <.icon name="hero-magnifying-glass" class="size-4" />
  </:inner_prefix>
</.autocomplete>

<!-- Server-side search -->
<.autocomplete
  name="movie"
  options={@movies}
  on_search="search_movies"
  search_threshold={2}
  clearable
  placeholder="Type to search movies..."
/>

Custom Option Rendering

<.autocomplete
  name="users"
  placeholder="Search team members..."
  options={[{"John Doe", "john"}, {"Jane Smith", "jane"}]}
>
  <:option :let={{label, value}}>
    <div class="flex items-center gap-3">
      <div class="size-8 rounded-full bg-gradient-to-r from-blue-500 to-purple-500 flex items-center justify-center text-white text-sm font-bold">
        {String.first(label)}
      </div>
      <div>
        <div class="font-medium text-sm">{label}</div>
        <div class="text-xs text-zinc-500">@{value}</div>
      </div>
    </div>
  </:option>
</.autocomplete>

Badge

The Badge component provides versatile visual markers for status indicators, categories, and notification counts with semantic colors, size variants, and visual styles.

Attributes

• class (any, optional): Additional CSS classes for the badge element
• color (string, default: "primary"): Semantic color - "primary", "info", "success", "warning", "danger"
• size (string, default: "md"): Size variant - "xs", "sm", "md", "lg", "xl"
• variant (string, default: "surface"): Visual style - "solid", "soft", "surface", "outline", "dashed", "ghost"
• rest: Additional HTML attributes

Slots

• inner_block (required): Content displayed within the badge (text, icons, or both)

Usage Examples

Colors and Variants

<.badge>Default Badge</.badge>
<.badge color="success">Active</.badge>
<.badge color="danger" size="lg">Error</.badge>
<.badge variant="ghost" color="info">Draft</.badge>

<.badge variant="solid" color="success">High Emphasis</.badge>
<.badge variant="soft" color="info">Medium Emphasis</.badge>
<.badge variant="outline" color="primary">Outline</.badge>

Size Variants

<.badge size="xs">Extra Small</.badge>
<.badge size="sm">Small</.badge>
<.badge size="lg">Large</.badge>

With Icons and Interactive

<.badge color="success">
  <.icon name="hero-check-circle" class="icon" /> Verified
</.badge>

<!-- Toggle selection state -->
<.badge
  color={if @selected, do: "primary", else: "info"}
  variant={if @selected, do: "solid", else: "dashed"}
  phx-click="toggle_selection"
  class="cursor-pointer"
>
  <.icon :if={@selected} name="hero-check" class="icon" />
  Category
</.badge>

Button

The Button component provides consistent, accessible, and visually appealing interactive elements for actions and navigation. It automatically renders either a <button> or <a> tag based on provided attributes.

Components

• button: Interactive button/link element
• button_group: Container to group multiple buttons visually

Attributes

button

• color (string, default: "primary"): Semantic color - "primary", "danger", "warning", "success", "info"
• size (string, default: "md"): Size variant - "xs", "sm", "md", "lg", "xl", "icon-xs", "icon-sm", "icon-md", "icon", "icon-lg", "icon-xl"
• variant (string, default: "outline"): Visual style - "solid", "soft", "surface", "outline", "dashed", "ghost"
• disabled (boolean, default: false): Whether the button is disabled
• class (any, optional): Additional CSS classes for the button
• rest: Additional HTML attributes (supports both button and anchor attributes)

button_group

• class (any, optional): Additional CSS classes for the group container
• rest: Additional HTML attributes for the group container

Slots

button

• inner_block (required): Content displayed within the button (text, icons, etc.)

button_group

• inner_block (required): Buttons to be grouped together

Usage Examples

Basic Buttons and Variants

<.button>Outline Button (Default)</.button>
<.button variant="solid" color="primary">Solid Button</.button>
<.button variant="soft" color="primary">Soft Button</.button>
<.button variant="ghost">Ghost Button</.button>

Colors and Sizes

<.button color="primary" variant="solid">Primary</.button>
<.button color="danger" variant="soft">Danger</.button>
<.button color="success" variant="surface">Success</.button>

<.button size="xs">Extra Small</.button>
<.button size="lg">Large</.button>
<.button size="xl">Extra Large</.button>

Icon Buttons

<.button size="icon-sm">
  <.icon name="hero-pencil" class="icon" />
</.button>

<.button size="icon" variant="solid" color="primary">
  <.icon name="hero-magnifying-glass" class="icon" />
</.button>

<.button size="lg" variant="solid" color="success">
  <.icon name="hero-check-circle" class="icon" /> Order Confirmed
</.button>

Automatic Link Rendering

<!-- Renders as <a> tag -->
<.button navigate={~p"/dashboard"} variant="solid" color="primary">
  Go to Dashboard
</.button>

<.button href="https://example.com" target="_blank" variant="soft">
  External Link
</.button>

Interactive Examples

<!-- Danger Action -->
<.button variant="solid" color="danger" phx-click="delete_item" phx-value-id={@item.id} phx-confirm="Are you sure?">
  <.icon name="hero-trash" class="icon" />
  Delete Item
</.button>

<!-- Icon-Only with ARIA label -->
<.button size="icon" variant="ghost" phx-click="show-details" phx-value-id={@user.id} aria-label="View user details">
  <.icon name="hero-eye" class="icon" />
</.button>

Button Group

<.button_group>
  <.button>Year</.button>
  <.button>Month</.button>
  <.button>Week</.button>
</.button_group>

Checkbox

The Checkbox component provides versatile checkbox inputs for capturing single and multiple selections. It offers both standard and card variants with comprehensive form integration and accessibility features.

Components

• checkbox: Single checkbox input for boolean or single-value selections
• checkbox_group: Container for multiple related checkbox selections

Attributes

checkbox

• id (any, optional): Unique identifier for the checkbox
• name (any): Form name for the checkbox (required when not using field)
• checked (boolean, optional): Whether the checkbox is checked
• value (any, optional): Value associated with the checkbox
• errors (list, default: []): List of error messages
• label (string, optional): Primary label for the checkbox
• sublabel (string, optional): Additional context beside the main label
• description (string, optional): Detailed description below the label
• class (any, optional): Additional CSS classes for the checkbox
• field (Phoenix.HTML.FormField, optional): Form field to bind to
• variant (string, optional): Visual variant - nil (default), "card"
• control (string, optional): Position of checkbox in card variant - "left", "right"
• rest: Additional HTML attributes

checkbox_group

• id (any, optional): Unique identifier for the checkbox group
• name (string): Form name for the checkbox group (required when not using field)
• value (any, optional): Current value(s) of the checkbox group (list of selected values)
• label (string, optional): Primary label for the checkbox group
• sublabel (string, optional): Additional context beside the main label
• description (string, optional): Detailed description of the checkbox group
• errors (list, default: []): List of error messages
• class (any, optional): Additional CSS classes for the group container
• field (Phoenix.HTML.FormField, optional): Form field to bind to
• disabled (boolean, default: false): Disable all checkboxes in the group
• variant (string, optional): Visual variant - nil (default), "card"
• control (string, optional): Position of checkbox in card variant - "left", "right"
• rest: Additional HTML attributes

Slots

checkbox

• inner_block (optional): Custom content for the checkbox (replaces standard label structure in card variants)

checkbox_group

• checkbox (required): Individual checkboxes within the group

Usage Examples

Basic Checkbox and Form Integration

<.checkbox
  name="terms"
  label="I agree to the terms and conditions"
  value="accepted"
/>

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <.checkbox
    field={f[:marketing_emails]}
    label="Marketing emails"
    sublabel="Receive updates about new features and promotions"
  />
</.form>

Card Variant

<.checkbox
  control="left"
  field={f[:notifications]}
  variant="card"
  label="Push Notifications"
  sublabel="Stay informed"
  description="Get real-time updates for messages and activity"
  value="enabled"
/>

Checkbox Group

<.checkbox_group
  name="preferences"
  label="Notification Preferences"
  description="Choose when you want to receive notifications"
>
  <:checkbox value="email" label="Email notifications" />
  <:checkbox value="push" label="Push notifications" />
  <:checkbox value="sms" label="SMS notifications" />
</.checkbox_group>

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <.checkbox_group
    field={f[:notification_preferences]}
    label="Notification Preferences"
    description="Choose how you want to be notified"
  >
    <:checkbox value="email" label="Email" sublabel="Get notified via email" />
    <:checkbox value="push" label="Push" sublabel="Receive push notifications" />
  </.checkbox_group>
</.form>

Custom Card Content

<.checkbox variant="card" name="feature" value="advanced">
  <div class="flex items-center gap-3">
    <div class="p-2 rounded bg-blue-100">
      <.icon name="hero-star" class="size-5 text-blue-600" />
    </div>
    <div>
      <h3 class="font-medium">Advanced Features</h3>
      <p class="text-sm text-gray-600">Access premium functionality</p>
    </div>
  </div>
</.checkbox>

DatePicker

The DatePicker component provides calendar-based date selection with support for single dates, multiple dates, date ranges, and time selection. It includes configurable sizing and affix slots for UI customization.

Components

• date_picker: Single date selection with optional multiple date support
• date_time_picker: Date and time selection
• date_range_picker: Date range selection with start and end dates

Attributes

date_picker

• id (any, optional): Unique identifier for the date picker
• name (any): Form name for the date picker (required when not using field)
• field (Phoenix.HTML.FormField, optional): Form field to bind to
• value (any, optional): Current selected value
• multiple (boolean, default: false): Allow selecting multiple dates
• label (string, optional): Primary label for the date picker
• sublabel (string, optional): Additional context beside the main label
• description (string, optional): Detailed description below the label
• help_text (string, optional): Help text displayed below the component
• placeholder (string, optional): Text to display when no date is selected
• size (string, default: "md"): Size variant - "xs", "sm", "md", "lg", "xl"
• min (Date/string, optional): Minimum selectable date
• max (Date/string, optional): Maximum selectable date
• disabled (boolean, default: false): Disable the date picker
• errors (list, default: []): List of error messages
• display_format (string, default: "%b %-d, %Y"): Format for displaying selected dates
• week_start (integer, default: 0): Day of week to start calendar (0=Sunday, 1=Monday, etc.)
• rest: Additional HTML attributes

date_time_picker

• All attributes from date_picker plus:
• time_format (string, default: "24"): Time format - "12" (12-hour) or "24" (24-hour)

date_range_picker

• id (any, optional): Unique identifier for the date range picker
• start_name (string): Form name for the start date (required when not using fields)
• end_name (string): Form name for the end date (required when not using fields)
• start_field (Phoenix.HTML.FormField, optional): Start date form field to bind to
• end_field (Phoenix.HTML.FormField, optional): End date form field to bind to
• start_value (any, optional): Current start date value
• end_value (any, optional): Current end date value
• Plus other shared attributes

Slots (All Components)

• inner_prefix (optional): Content inside the field border, before the date display
• outer_prefix (optional): Content outside and before the field
• inner_suffix (optional): Content inside the field border, after the date display
• outer_suffix (optional): Content outside and after the field

Usage Examples

Basic Date Pickers

<.date_picker
  name="appointment"
  label="Appointment Date"
  placeholder="Select a date"
/>

<.date_time_picker
  name="meeting"
  label="Meeting Time"
  time_format="12"
  placeholder="Select date and time"
/>

<.date_range_picker
  start_name="check_in"
  end_name="check_out"
  label="Stay Period"
  placeholder="Select date range"
/>

Size Variants and Labels

<.date_picker name="sm" size="sm" label="Small Date" placeholder="Small" />
<.date_picker name="lg" size="lg" label="Large Date" placeholder="Large" />

<.date_picker
  name="event_date"
  label="Event Date"
  sublabel="Required"
  description="Choose when your event will take place"
  help_text="Events can be scheduled up to 6 months in advance"
  placeholder="Select event date"
/>

Date Constraints and Multiple Selection

<!-- Future dates only -->
<.date_picker
  name="appointment"
  label="Appointment Date"
  min={Date.utc_today()}
  max={Date.add(Date.utc_today(), 60)}
  placeholder="Select your appointment date"
/>

<.date_picker
  name="available_dates"
  label="Available Dates"
  multiple
  placeholder="Select multiple dates"
/>

Form Integration with Affixes

<.form :let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.date_picker
    field={f[:appointment_date]}
    label="Appointment Date"
    placeholder="Choose date"
  />

  <.date_range_picker
    start_field={f[:start_date]}
    end_field={f[:end_date]}
    label="Date Range"
    placeholder="Choose date range"
  />
</.form>

<!-- With calendar icon -->
<.date_picker name="appointment" label="Appointment Date" placeholder="Select date">
  <:inner_prefix>
    <.icon name="hero-calendar-days" class="icon" />
  </:inner_prefix>
</.date_picker>

Dropdown

The Dropdown component provides a comprehensive system for creating accessible, interactive menus and selection interfaces with proper keyboard navigation and focus management.

Components

• dropdown: Main dropdown container
• dropdown_link: Link menu item for navigation
• dropdown_button: Button menu item for actions
• dropdown_header: Section header for organizing menu items
• dropdown_separator: Visual separator between menu sections
• dropdown_custom: Custom content container for rich menu items

Attributes

dropdown

• id (string, optional): Unique identifier for the dropdown component
• label (string, default: "Menu"): Text label for the default toggle button
• class (any, optional): Additional CSS classes for the dropdown container
• placement (string, default: "bottom-start"): Menu position relative to toggle
• open_on_hover (boolean, default: false): Enable hover-based opening
• hover_open_delay (integer, default: 100): Delay before opening on hover (ms)
• hover_close_delay (integer, default: 300): Delay before closing when leaving hover (ms)
• rest: Additional HTML attributes

Other dropdown components

• class (any, optional): Additional CSS classes for the element
• rest: Additional HTML attributes

Slots

dropdown

• toggle (optional): Custom toggle element to replace the default button
• inner_block (required): Menu items and content

All other dropdown components

• inner_block (required): Content for the menu item/element

Usage Examples

Basic Dropdown

<.dropdown>
  <.dropdown_link navigate={~p"/profile"}>Profile</.dropdown_link>
  <.dropdown_link navigate={~p"/settings"}>Settings</.dropdown_link>
  <.dropdown_separator />
  <.dropdown_link href={~p"/logout"} method="delete">Sign Out</.dropdown_link>
</.dropdown>

Custom Toggle and Rich Content

<.dropdown>
  <:toggle>
    <button class="flex items-center gap-x-2 bg-zinc-200/50 rounded-lg p-2">
      <img src={~p"/images/human-avatar-01.png"} alt="User" class="size-6 rounded-lg" />
      <div class="text-sm text-gray-800 font-semibold">John Doe</div>
      <.icon name="hero-chevron-down" class="size-4" />
    </button>
  </:toggle>
  <.dropdown_button>Profile</.dropdown_button>
  <.dropdown_button>Settings</.dropdown_button>
</.dropdown>

<.dropdown class="w-64">
  <.dropdown_custom class="flex items-center p-2">
    <img src="https://i.pravatar.cc/150?u=1" alt="Avatar" class="size-9 rounded-full" />
    <div class="flex flex-col ml-3">
      <span class="text-sm font-medium">Emma Johnson</span>
      <span class="text-xs text-zinc-500">emma@acme.com</span>
    </div>
  </.dropdown_custom>

  <.dropdown_separator />

  <.dropdown_header>Account</.dropdown_header>
  <.dropdown_link navigate={~p"/profile"}>Profile</.dropdown_link>
  <.dropdown_link navigate={~p"/billing"}>Billing</.dropdown_link>
</.dropdown>

Hover Interaction and Button Actions

<.dropdown open_on_hover hover_open_delay={200} hover_close_delay={300}>
  <.dropdown_link navigate={~p"/profile"}>Profile</.dropdown_link>
  <.dropdown_link navigate={~p"/settings"}>Settings</.dropdown_link>
</.dropdown>

<.dropdown>
  <.dropdown_button phx-click="export_data">Export Data</.dropdown_button>
  <.dropdown_button phx-click="import_data">Import Data</.dropdown_button>
  <.dropdown_separator />
  <.dropdown_button phx-click="delete_all" phx-confirm="Are you sure?">
    Delete All
  </.dropdown_button>
</.dropdown>

Input

The Input component provides versatile text input fields with support for various types, sizes, form integration, and customizable prefix/suffix content both inside and outside the input field.

Components

• input: Main text input component
• input_group: Container for visually grouping multiple related inputs

Attributes

input

• id (any, optional): HTML id attribute for the input element
• name (any): Form name for the input (required when not using field)
• field (Phoenix.HTML.FormField, optional): Form field to bind to
• value (any, optional): Current input value
• type (string, default: "text"): HTML input type
• label (string, optional): Primary label for the input
• sublabel (string, optional): Additional context beside the main label
• description (string, optional): Detailed description below the label
• help_text (string, optional): Help text displayed below the input
• placeholder (string, optional): Placeholder text
• size (string, default: "md"): Size variant - "xs", "sm", "md", "lg", "xl"
• disabled (boolean, default: false): Disable the input
• readonly (boolean, optional): Make input readonly
• errors (list, default: []): List of error messages
• class (any, optional): Additional CSS classes
• rest: Additional HTML attributes

input_group

• class (any, optional): Additional CSS classes for the group container
• label (string, optional): Primary label for the input group
• sublabel (string, optional): Additional context beside the main label
• description (string, optional): Detailed description of the input group
• help_text (string, optional): Help text displayed below the group
• rest: Additional HTML attributes

Slots

input

• inner_prefix (optional): Content inside the input border, before the text
• outer_prefix (optional): Content outside and before the input field
• inner_suffix (optional): Content inside the input border, after the text
• outer_suffix (optional): Content outside and after the input field

input_group

• inner_block (required): Input elements and controls to be grouped

Usage Examples

Basic Input and Size Variants

<.input name="username" label="Username" placeholder="Enter username..." />
<.input name="password" type="password" label="Password" />
<.input name="email" type="email" label="Email" />

<.input name="input_sm" size="sm" placeholder="Small" />
<.input name="input_lg" size="lg" placeholder="Large" />
<.input name="input_xl" size="xl" placeholder="Extra Large" />

Complete Labeling and Form Integration

<.input
  name="full_example"
  label="Email Address"
  sublabel="(required)"
  description="We'll send a confirmation link here."
  help_text="We never share your email."
  placeholder="you@example.com"
/>

<.form :let={f} for={@form}>
  <.input field={f[:email]} type="email" label="Email" />
  <.input field={f[:password]} type="password" label="Password" />
</.form>

Input States and Types

<!-- Disabled and readonly -->
<.input name="disabled_input" value="Cannot change" disabled />
<.input name="readonly_input" value="Readonly value" readonly />

<!-- Different types -->
<.input type="date" name="date_input" label="Appointment Date" />
<.input type="number" name="count" label="Quantity" min="1" max="10" />
<.input type="search" name="site_search" placeholder="Search site..." />

Inner Affixes

<!-- Email with icon -->
<.input name="email_icon" placeholder="user@example.com">
  <:inner_prefix>
    <.icon name="hero-at-symbol" class="icon" />
  </:inner_prefix>
</.input>

<!-- Password with visibility toggle -->
<.input name="password_toggle" type="password" value="secretpassword">
  <:inner_suffix>
    <.button variant="ghost" size="icon-sm" title="Show password">
      <.icon name="hero-eye" class="icon" />
    </button>
  </:inner_suffix>
</.input>

<!-- URL with static prefix -->
<.input name="url_prefix" placeholder="yourdomain.com">
  <:inner_prefix class="pointer-events-none text-zinc-500">https://www.</:inner_prefix>
</.input>

Outer Affixes

<!-- With send button -->
<.input name="invite_user" placeholder="user@example.com">
  <:inner_prefix>
    <.icon name="hero-at-symbol" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
    <.button variant="solid" color="primary">
      <.icon name="hero-paper-airplane" class="icon" /> Invite
    </button>
  </:outer_suffix>
</.input>

<!-- Currency input with prefix and suffix -->
<.input name="website_url" placeholder="mysite">
  <:outer_prefix class="px-2 text-zinc-500">https://</:outer_prefix>
  <:outer_suffix class="px-2 text-zinc-500">.example.com</:outer_suffix>
</.input>

Input Groups

<!-- Name inputs -->
<.input_group label="Full Name">
  <.input name="first_name" placeholder="First Name" />
  <.input name="last_name" placeholder="Last Name" />
</.input_group>

<!-- Price range with separator -->
<.input_group label="Price Range">
  <.input name="min_price" placeholder="Min price">
    <:inner_prefix>$</:inner_prefix>
  </.input>
  <div class="shrink-0 bg-gray-100 border-y border-gray-200 shadow-sm self-stretch flex items-center justify-center px-2 text-gray-500">
    to
  </div>
  <.input name="max_price" placeholder="Max price">
    <:inner_prefix>$</:inner_prefix>
  </.input>
</.input_group>

Loading

The Loading component provides versatile animated loading indicators for displaying loading states with multiple animation styles and customization options.

Attributes

• class (any, optional): Additional CSS classes for customizing size and color (default: size-5, text-zinc-600)
• duration (integer, default: 600): Duration of one complete animation cycle in milliseconds
• variant (string, default: "ring"): Animation style - "ring", "ring-bg", "dots-bounce", "dots-fade", "dots-scale"
• rest: Additional HTML attributes

Usage Examples

Animation Variants

<.loading />
<.loading variant="ring-bg" />
<.loading variant="dots-bounce" />
<.loading variant="dots-fade" />
<.loading variant="dots-scale" />

Size and Color Variations

<.loading class="size-4" />
<.loading class="size-8" />
<.loading class="size-12" />

<.loading class="text-blue-500" />
<.loading class="text-green-500" />
<.loading class="text-red-500" />

Button Loading States

<.button disabled>
  <.loading class="size-4" /> Loading...
</.button>

<.button variant="solid" color="primary" disabled>
  <.loading class="size-4 text-white" /> Processing
</.button>

Page and Section Loading

<!-- Full page loading -->
<div class="flex items-center justify-center min-h-[400px]">
  <.loading class="size-8" />
</div>

<!-- Loading overlay -->
<div class="relative">
  <div class="absolute inset-0 flex items-center justify-center bg-white/80 rounded">
    <.loading class="size-6" />
  </div>
  <!-- Content being loaded -->
</div>

<!-- Inline loading -->
<p>Processing your request <.loading class="size-4 inline" variant="dots-bounce" /></p>

Modal

The Modal component provides a powerful and accessible modal overlay for displaying focused content with LiveView integration, supporting both client-side and server-side control.

Attributes

• id (string, required): Unique identifier for the modal component
• open (boolean, default: false): Whether the modal is initially open
• on_close (JS, optional): JavaScript commands to execute when the modal closes
• on_open (JS, optional): JavaScript commands to execute when the modal opens
• class (any, optional): Additional CSS classes for the modal content container
• container_class (any, optional): CSS classes for the outer modal container
• close_on_esc (boolean, default: true): Whether pressing ESC closes the modal
• close_on_outside_click (boolean, default: true): Whether clicking outside closes the modal
• prevent_closing (boolean, default: false): Prevent all client-side closing behaviors
• hide_close_button (boolean, default: false): Hide the default close button
• animation (string, default: "transition duration-300 ease-out"): Animation classes
• animation_enter (string, default: "opacity-100 scale-100"): Enter animation classes
• animation_leave (string, default: "opacity-0 scale-95"): Leave animation classes
• backdrop_class (string, optional): Custom classes for the modal backdrop
• placement (string, default: "center"): Modal positioning on screen
• rest: Additional HTML attributes

Slots

• inner_block (required): Content displayed within the modal

Usage Examples

Basic Modal

<.button phx-click={Fluxon.open_dialog("basic-modal")}>Open Modal</.button>

<.modal id="basic-modal">
  <div class="p-6">
    <h2 class="text-lg font-semibold mb-4">Modal Title</h2>
    <p>This is the modal content.</p>

    <div class="flex gap-2 mt-6">
      <.button phx-click={Fluxon.close_dialog("basic-modal")}>Close</.button>
    </div>
  </div>
</.modal>

Server-Side Control

<.button phx-click="show_modal">Open Server Modal</.button>

<.modal id="server-modal" open={@show_modal} on_close={JS.push("hide_modal")}>
  <div class="p-6">
    <h2 class="text-lg font-semibold">Server Controlled Modal</h2>
    <p>This modal is controlled by server state.</p>
    <.button phx-click="hide_modal" class="mt-4">Close</.button>
  </div>
</.modal>

<!-- Server-only control -->
<.modal id="secure-modal" open={@show_secure_modal} prevent_closing>
  <div class="p-6">
    <h2 class="text-lg font-semibold text-red-600">Critical Operation</h2>
    <p>This modal can only be closed through server commands.</p>
    <.button phx-click="hide_secure_modal" color="danger" class="mt-4">
      Complete Action
    </.button>
  </div>
</.modal>

Custom Styling and Form Modal

<!-- Large modal -->
<.modal
  id="large-modal"
  class="w-full max-w-4xl max-h-[80vh] overflow-auto"
  container_class="p-4"
>
  <div class="p-8">
    <h2 class="text-2xl font-bold mb-6">Large Modal</h2>
    <p>This modal has custom sizing and scrolling behavior.</p>
  </div>
</.modal>

<!-- Form modal -->
<.modal id="form-modal" on_close={JS.push("reset_form")}>
  <div class="p-6">
    <h2 class="text-lg font-semibold mb-4">Create User</h2>

    <.form :let={f} for={@changeset} phx-change="validate" phx-submit="create_user">
      <.input field={f[:name]} label="Full Name" />
      <.input field={f[:email]} type="email" label="Email" />

      <div class="flex gap-2 mt-6">
        <.button type="submit" disabled={!@changeset.valid?}>
          Create User
        </.button>
        <.button
          type="button"
          variant="outline"
          phx-click={Fluxon.close_dialog("form-modal")}
        >
          Cancel
        </.button>
      </div>
    </.form>
  </div>
</.modal>

Confirmation Modal

<.modal id="confirm-delete" class="w-96">
  <div class="p-6 text-center">
    <div class="w-12 h-12 mx-auto mb-4 bg-red-100 rounded-full flex items-center justify-center">
      <.icon name="hero-exclamation-triangle" class="size-6 text-red-600" />
    </div>

    <h2 class="text-lg font-semibold mb-2">Delete Item</h2>
    <p class="text-gray-600 mb-6">
      Are you sure you want to delete this item? This action cannot be undone.
    </p>

    <div class="flex gap-2 justify-center">
      <.button
        color="danger"
        phx-click="confirm_delete"
        phx-value-id={@delete_item_id}
      >
        Delete
      </.button>
      <.button
        variant="outline"
        phx-click={Fluxon.close_dialog("confirm-delete")}
      >
        Cancel
      </.button>
    </div>
  </div>
</.modal>

Navlist

The Navlist component provides a comprehensive navigation system for building structured, accessible navigation menus with support for sections, headings, and interactive links.

Components

• navlist: Main navigation container that provides structure and spacing
• navheading: Optional section headers for organizing navigation groups
• navlink: Interactive navigation items with LiveView integration

Attributes

navlist

• heading (string, optional): Primary heading for the navigation section
• class (any, optional): Additional CSS classes for the navigation container
• rest: Additional HTML attributes for the nav container

navheading

• class (any, optional): Additional CSS classes for the heading element
• rest: Additional HTML attributes

navlink

• class (any, optional): Additional CSS classes for the navigation link
• active (boolean, default: false): Whether this navigation item is currently active
• rest: Additional HTML attributes (supports navigation attributes like navigate, patch, href, etc.)

Slots

navlist

• inner_block (required): Navigation items and headings

navheading

• inner_block (required): Heading content

navlink

• inner_block (required): Link content (text, icons, badges, etc.)

Usage Examples

Basic Navigation

<.navlist heading="Main Navigation">
  <.navlink navigate={~p"/dashboard"} active>
    <.icon name="hero-home" class="size-5" /> Dashboard
  </.navlink>
  <.navlink navigate={~p"/projects"}>
    <.icon name="hero-folder" class="size-5" /> Projects
  </.navlink>
  <.navlink navigate={~p"/settings"}>
    <.icon name="hero-cog-6-tooth" class="size-5" /> Settings
  </.navlink>
</.navlist>

Multiple Sections

<.navlist heading="Main">
  <.navlink navigate={~p"/dashboard"} active>
    <.icon name="hero-home" class="size-5" /> Dashboard
  </.navlink>
  <.navlink navigate={~p"/projects"}>
    <.icon name="hero-folder" class="size-5" /> Projects
  </.navlink>
</.navlist>

<.navlist heading="Settings">
  <.navlink navigate={~p"/profile"}>
    <.icon name="hero-user" class="size-5" /> Profile
  </.navlink>
  <.navlink navigate={~p"/preferences"}>
    <.icon name="hero-cog-6-tooth" class="size-5" /> Preferences
  </.navlink>
</.navlist>

Navigation with Badges

<.navlist heading="Inbox">
  <.navlink navigate={~p"/inbox/unread"}>
    <.icon name="hero-envelope" class="size-5" />
    Unread
    <.badge variant="solid" color="danger" class="ml-auto">23</.badge>
  </.navlink>

  <.navlink navigate={~p"/inbox/starred"}>
    <.icon name="hero-star" class="size-5" />
    Starred
    <.badge variant="soft" color="warning" class="ml-auto">5</.badge>
  </.navlink>
</.navlist>

External Links and Actions

<.navlist heading="Resources">
  <.navlink href="https://docs.example.com" target="_blank">
    <.icon name="hero-document-text" class="size-5" />
    Documentation
    <.icon name="hero-arrow-top-right-on-square" class="size-4 ml-auto text-gray-400" />
  </.navlink>
</.navlist>

<.navlist heading="Actions">
  <.navlink phx-click="export_data">
    <.icon name="hero-arrow-down-tray" class="size-5" />
    Export Data
  </.navlink>

  <.navlink phx-click="refresh_data">
    <.icon name="hero-arrow-path" class="size-5" />
    Refresh
  </.navlink>
</.navlist>

Popover

A powerful and accessible popover component that displays floating content anchored to a trigger element.

Attributes

• id (string, default: auto-generated): Optional unique identifier for the popover
• target (string, default: nil): CSS selector of an external element to use as positioning reference
• class (any, default: nil): Additional CSS classes for the popover content container
• open_on_hover (boolean, default: false): Opens popover on hover for tooltip-like behavior
• open_on_focus (boolean, default: false): Opens popover when trigger receives focus
• placement (string, default: "top"): Popover position - "top", "top-start", "top-end", "right", "right-start", "right-end", "left", "left-start", "left-end", "bottom", "bottom-start", "bottom-end"

Slots

• inner_block: The trigger element that will open the popover (optional when using target)
• content (required): The content to display in the popover

Usage Examples

Basic Tooltip

<.popover open_on_hover>
  <.icon name="hero-information-circle" class="text-zinc-400" />

  <:content>
    <p class="text-sm">The invoice will be generated at the end of the month.</p>
  </:content>
</.popover>

Interactive Menu and Form Help

<.popover placement="bottom-end" class="w-64">
  <.button variant="ghost">
    <.icon name="hero-cog-6-tooth" /> Settings
  </.button>

  <:content>
    <div class="space-y-4">
      <div class="flex items-center justify-between">
        <span class="text-sm font-medium">Dark Mode</span>
        <.switch name="dark_mode" checked />
      </div>
      <.button size="sm" class="w-full">
        Reset Preferences
      </.button>
    </div>
  </:content>
</.popover>

<.input name="api-key" label="API Key" value="sk_test_..." class="font-mono">
  <:inner_suffix>
    <.popover open_on_hover placement="right">
      <.icon name="hero-question-mark-circle" class="text-zinc-400" />

      <:content>
        <div class="max-w-xs space-y-2">
          <p class="text-sm font-medium">About API Keys</p>
          <p class="text-sm text-zinc-600">
            Your API key is used to authenticate requests. Keep it secure.
          </p>
        </div>
      </:content>
    </.popover>
  </:inner_suffix>
</.input>

Search Suggestions

<.popover open_on_focus placement="bottom-start" class="w-80">
  <.input type="search" placeholder="Search users..." phx-debounce="300" />

  <:content>
    <div :if={@loading} class="p-4 flex justify-center">
      <.loading />
    </div>
    <div :for={user <- @users} class="p-2 hover:bg-zinc-50 cursor-pointer">
      <div class="font-medium">{user.name}</div>
      <div class="text-sm text-zinc-600">{user.email}</div>
    </div>
  </:content>
</.popover>

Radio

A versatile radio component for building single-selection interfaces with rich styling options.

Attributes

• id (any, default: nil): The unique identifier for the radio group
• name (string, required when not using field): The form name for the radio group
• value (any): The current selected value of the radio group
• label (string, default: nil): The primary label for the radio group
• sublabel (string, default: nil): Additional context displayed beside the main label
• description (string, default: nil): Detailed description below the label
• errors (list, default: []): List of error messages
• class (any, default: nil): Additional CSS classes for the radio group container
• field (Phoenix.HTML.FormField): The form field to bind to
• disabled (boolean, default: false): Disables all radio buttons in the group
• variant (string, default: nil): Visual variant - nil (default) or "card"
• control (string): Controls radio position in card variants - "left" or "right"
• rest (global): Additional attributes

Slots

• radio (required): Defines individual radio buttons with attributes: value, label, sublabel, description, disabled, class, checked

Usage Examples

Basic Radio Group

<.radio_group name="system" value="debian" label="Operating System">
  <:radio value="ubuntu" label="Ubuntu" />
  <:radio value="debian" label="Debian" />
  <:radio value="fedora" label="Fedora" />
</.radio_group>

With Context and Form Integration

<.radio_group
  name="system"
  label="Operating System"
  sublabel="Choose your preferred OS"
  description="Select the operating system that best suits your needs"
>
  <:radio
    value="ubuntu"
    label="Ubuntu"
    sublabel="Popular and user-friendly"
    description="Ubuntu is a Debian-based Linux operating system"
  />
  <:radio
    value="debian"
    label="Debian"
    sublabel="Stable and reliable"
    description="Debian is composed of free and open-source software"
  />
</.radio_group>

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <.radio_group
    field={f[:subscription]}
    label="Subscription Plan"
    description="Choose your preferred subscription plan"
  >
    <:radio value="basic" label="Basic Plan" sublabel="$10/month" />
    <:radio value="pro" label="Pro Plan" sublabel="$20/month" />
    <:radio value="enterprise" label="Enterprise Plan" sublabel="$50/month" />
  </.radio_group>
</.form>

Card Variant

<.radio_group
  name="plan"
  label="Choose a plan"
  description="Choose the plan that best suits your needs."
  variant="card"
  control="left"
  class="gap-0"
>
  <:radio value="basic" label="Basic" sublabel="Perfect for small projects" class="rounded-none -my-px rounded-t-lg" />
  <:radio value="pro" label="Professional" checked sublabel="Most popular for growing teams" class="rounded-none -my-px" />
  <:radio value="business" label="Business" sublabel="Advanced features for larger teams" class="rounded-none -my-px rounded-b-lg" />
</.radio_group>

<.radio_group name="category" label="Category" variant="card" class="grid grid-cols-3">
  <:radio value="web-design" class="flex-1 group has-checked:border-blue-500 has-checked:bg-blue-50">
    <div class="flex flex-col justify-center items-center w-full gap-2">
      <.icon name="hero-computer-desktop" class="size-6 text-zinc-500 group-has-checked:text-blue-500" />
      <span class="font-medium text-sm group-has-checked:text-zinc-800">Web Design</span>
    </div>
  </:radio>
  <:radio value="ui-ux" class="flex-1 group has-checked:border-blue-500 has-checked:bg-blue-50">
    <div class="flex flex-col justify-center items-center w-full gap-2">
      <.icon name="hero-pencil" class="size-6 text-zinc-500 group-has-checked:text-blue-500" />
      <span class="font-medium text-sm group-has-checked:text-zinc-800">UI/UX Design</span>
    </div>
  </:radio>
</.radio_group>

Select

A select component that implements a modern, accessible selection interface with support for single and multiple selections.

Attributes

• id (any, default: nil): The unique identifier for the select component
• name (any, required when not using field): The form name for the select
• field (Phoenix.HTML.FormField): The form field to bind to
• native (boolean, default: false): Renders a native HTML select element instead of custom select
• class (any, default: nil): Additional CSS classes for the select component
• label (string, default: nil): The primary label for the select
• sublabel (string, default: nil): Additional context beside the main label
• help_text (string, default: nil): Help text displayed below the select
• description (string, default: nil): Description below the label but above select
• placeholder (string, default: nil): Text displayed when no option is selected
• searchable (boolean, default: false): Adds search input to filter options (custom select only)
• disabled (boolean, default: false): Disables the select component
• size (string, default: "md"): Controls select size - "xs", "sm", "md", "lg", "xl"
• search_input_placeholder (string, default: "Search..."): Placeholder for search input
• search_no_results_text (string, default: "No results found for %{query}."): No results text
• search_threshold (integer, default: 0): Minimum characters before filtering
• debounce (integer, default: 300): Debounce time for server searches
• on_search (string, default: nil): LiveView event name for server searches
• multiple (boolean, default: false): Allows selecting multiple options (not with native)
• value (any): Current selected value(s)
• errors (list, default: []): List of error messages
• options (list, required): List of options for the select
• max (integer, default: nil): Maximum selections when multiple
• clearable (boolean, default: false): Shows clear button
• rest (global): Additional attributes

Slots

• option: Optional slot for custom option rendering
• toggle: Optional slot for custom toggle rendering
• header: Optional slot for custom header content
• footer: Optional slot for custom footer content
• inner_prefix: Content inside select field before value display
• outer_prefix: Content outside and before select field
• inner_suffix: Content inside select field after value display
• outer_suffix: Content outside and after select field

Usage Examples

Basic and Full-featured Select

<.select
  name="country"
  options={[{"United States", "US"}, {"Canada", "CA"}]}
/>

<.select
  name="payment_method"
  label="Payment Method"
  sublabel="Select payment type"
  description="Choose your preferred payment method"
  help_text="We securely process all payment information"
  placeholder="Select payment method"
  options={[
    {"Credit Card", "credit_card"},
    {"PayPal", "paypal"},
    {"Bank Transfer", "bank_transfer"}
  ]}
/>

Native, Searchable and Multiple

<.select
  name="country"
  native
  options={[{"United States", "US"}, {"Canada", "CA"}]}
/>

<.select
  name="country"
  searchable
  search_input_placeholder="Search for a country"
  search_no_results_text="No countries found for %{query}"
  options={@countries}
/>

<.select
  name="countries"
  multiple
  max={3}
  clearable
  options={[{"United States", "US"},{"Canada", "CA"},{"Mexico", "MX"}]}
/>

Form Integration and Affixes

<.form :let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.select
    field={f[:country]}
    label="Country"
    options={@countries}
  />
</.form>

<.select name="category" options={@categories} placeholder="Select category">
  <:inner_prefix>
    <.icon name="hero-folder" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
    <.button size="md">Apply</.button>
  </:outer_suffix>
</.select>

Custom Option Rendering

<.select
  name="role"
  placeholder="Select role"
  options={[{"Admin", "admin"}, {"Editor", "editor"}, {"Viewer", "viewer"}]}
>
  <:option :let={{label, value}}>
    <div class="flex items-center justify-between rounded-lg py-2 px-3">
      <div>
        <div class="font-medium text-sm">{label}</div>
        <div class="text-zinc-500 text-xs">
          {case value do
            "admin" -> "Full access to all features"
            "editor" -> "Can create and modify content"
            "viewer" -> "Read-only access to content"
          end}
        </div>
      </div>
      <.icon :if={value == "admin"} name="hero-shield-check" class="size-4 text-blue-500" />
    </div>
  </:option>
</.select>

Separator

A versatile separator component for creating visual boundaries between content sections.

Attributes

• text (string, default: nil): Optional text to display in the center of the separator
• vertical (boolean, default: false): Renders a vertical separator instead of horizontal
• class (any, default: nil): Additional CSS classes

Usage Examples

Basic Separators

<div class="py-2">Content above</div>
<.separator />
<div class="py-2">Content below</div>

<div class="flex h-8 items-center gap-4">
  <span>Left</span>
  <.separator vertical />
  <span>Right</span>
</div>

<.separator text="or" />
<.separator text="Section" class="my-6" />

Form and Navigation Usage

<form class="space-y-4">
  <.input name="email" type="email" placeholder="Email" />
  <.input name="password" type="password" placeholder="Password" />
  <.button type="submit" class="w-full">Sign In</.button>

  <.separator text="or" />

  <.button type="button" variant="outline" class="w-full">
    Sign in with Google
  </.button>
</form>

<div class="flex items-center gap-4">
  <span>Profile</span>
  <.separator vertical />
  <span>Settings</span>
  <.separator vertical />
  <span>Logout</span>
</div>

Sheet

A powerful and accessible sheet component that provides a sliding panel interface for displaying content from screen edges.

Attributes

• id (string, required): The unique identifier for the sheet component
• open (boolean, default: false): Whether the sheet is initially open
• on_close (JS, default: %JS{}): JavaScript commands to execute when sheet closes
• on_open (JS, default: %JS{}): JavaScript commands to execute when sheet opens
• class (any, default: ""): Additional CSS classes for sheet content container
• close_on_esc (boolean, default: true): Whether to close sheet when Escape is pressed
• close_on_outside_click (boolean, default: true): Whether to close when clicking outside
• prevent_closing (boolean, default: false): Prevents sheet from being closed through standard interactions
• hide_close_button (boolean, default: false): Whether to hide the close button
• animation (string, default: "transition duration-200 ease-in-out"): Base animation classes
• animation_enter (string): Classes applied when sheet enters (auto-set based on placement)
• animation_leave (string): Classes applied when sheet leaves (auto-set based on placement)
• backdrop_class (string, default: ""): Additional CSS classes for backdrop overlay
• placement (string, default: "left"): Edge the sheet slides from - "left", "right", "top", "bottom"

Slots

• inner_block (required): The content of the sheet

Usage Examples

Basic Client-Side Control

<.button phx-click={Fluxon.open_dialog("filters-sheet")}>Filters</.button>

<.sheet id="filters-sheet">
  <h3 class="text-lg font-semibold mb-4">Filters</h3>

  <div class="space-y-4">
    <!-- Filter content -->
  </div>

  <.button phx-click={Fluxon.close_dialog("filters-sheet")}>Apply</.button>
</.sheet>

Server-Side Control

<.button phx-click="show-sheet">Open Filters</.button>

<.sheet id="filters-sheet" open={@show_filters}>
  <h3 class="text-lg font-semibold">Server-controlled Sheet</h3>
</.sheet>

<!-- With state sync -->
<.sheet
  id="filters-sheet"
  open={@show_filters}
  on_close={JS.push("hide_filters")}
>
  <h3 class="text-lg font-semibold">Filters with State Sync</h3>
</.sheet>

Different Placements

<!-- Left drawer for navigation -->
<.sheet id="nav-sheet" placement="left" class="w-80">
  <nav class="space-y-2">
    <.navlink href="/dashboard">Dashboard</.navlink>
    <.navlink href="/projects">Projects</.navlink>
  </nav>
</.sheet>

<!-- Right sheet for details -->
<.sheet id="details-sheet" placement="right" class="w-96">
  <h3 class="text-lg font-semibold">Details</h3>
  <p>Detailed information goes here.</p>
</.sheet>

<!-- Bottom action sheet -->
<.sheet id="actions-sheet" placement="bottom" class="h-96">
  <div class="space-y-3">
    <.button class="w-full">Share</.button>
    <.button class="w-full">Copy Link</.button>
    <.button class="w-full">Delete</.button>
  </div>
</.sheet>

Form in Sheet

<.sheet id="new-user-sheet" placement="right" class="w-96">
  <.form for={@form} phx-submit="save_user">
    <div class="space-y-4">
      <header class="mb-4">
        <h2 class="text-lg font-semibold">New User</h2>
        <p class="text-sm text-zinc-600">Create a new user account.</p>
      </header>

      <.input field={@form[:name]} label="Name" />
      <.input field={@form[:email]} type="email" label="Email" />

      <div class="flex justify-end gap-3 mt-6">
        <.button phx-click={Fluxon.close_dialog("new-user-sheet")}>
          Cancel
        </.button>
        <.button type="submit" phx-disable-with="Creating...">
          Create User
        </.button>
      </div>
    </div>
  </.form>
</.sheet>

Switch

A toggle switch component for binary choices and settings with immediate effect.

Attributes

• id (any, default: nil): The unique identifier for the switch
• name (string, required when not using field): The form name for the switch
• class (any, default: nil): Additional CSS classes for the switch wrapper
• checked (boolean): Whether the switch is in the on position
• disabled (boolean, default: false): Disables the switch
• value (any): The value associated with the switch
• label (string, default: nil): The primary label for the switch
• sublabel (string, default: nil): Additional context beside the main label
• description (string, default: nil): Detailed description below the label
• size (string, default: "md"): Controls switch size - "sm", "md", "lg"
• color (string, default: "primary"): Color theme when on - "primary", "danger", "success", "warning", "info"
• field (Phoenix.HTML.FormField): The form field to bind to
• rest (global): Additional attributes

Usage Examples

Basic Switch and Size Variants

<.switch
  name="notifications"
  label="Enable Notifications"
  checked={@settings.notifications}
  phx-click="toggle_setting"
  phx-value-setting="notifications"
/>

<.switch name="small_switch" label="Small Switch" size="sm" checked={@settings.compact_mode} />
<.switch name="large_switch" label="Large Switch" size="lg" checked={@settings.important_setting} />

Labels and Context

<.switch name="simple" label="Enable Feature" checked={@feature_enabled} />

<.switch
  name="with_sublabel"
  label="Auto Save"
  sublabel="Recommended"
  checked={@settings.auto_save}
/>

<.switch
  name="comprehensive"
  label="Advanced Analytics"
  sublabel="Beta"
  description="Share detailed usage patterns to help improve the product experience"
  checked={@settings.analytics_enabled}
/>

Color Variants and Form Integration

<.switch name="primary" label="Default Setting" color="primary" checked={@settings.default} />
<.switch name="success" label="Enable Backup" color="success" checked={@settings.backup_enabled} />
<.switch name="danger" label="Public Profile" color="danger" checked={@settings.public_profile} />

<.form :let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.switch
    field={f[:notifications_enabled]}
    label="Push Notifications"
    sublabel="Real-time updates"
    description="Receive notifications about important account activity"
  />

  <.switch
    field={f[:email_marketing]}
    label="Email Marketing"
    sublabel="Optional"
    description="Receive promotional emails about new features"
  />
</.form>

Disabled States

<.switch
  name="disabled_off"
  label="Unavailable Feature"
  description="This feature is currently unavailable"
  disabled
  checked={false}
/>

<.switch
  name="disabled_on"
  label="Premium Feature"
  sublabel="Upgrade required"
  description="This feature requires a premium subscription"
  disabled
  checked={true}
/>

Table

A comprehensive table system for displaying structured data with rich customization options.

Components

• table: The main container providing structure and responsive behavior
• table_head: Header section with column definitions
• table_body: Content section containing rows of data
• table_row: Individual data rows with cell content

Attributes

• All components have class (optional) and rest attributes for customization

Slots

table

• inner_block (required): Usually contains table_head and table_body components

table_head

• col (required): Defines table columns rendered as th elements

table_body

• inner_block (required): Usually contains table_row components

table_row

• cell (required): Defines table cells with custom content and styling

Usage Examples

Basic Table

<.table>
  <.table_head>
    <:col>Name</:col>
    <:col>Status</:col>
    <:col>Email</:col>
  </.table_head>

  <.table_body>
    <.table_row>
      <:cell>Alice Smith</:cell>
      <:cell>New</:cell>
      <:cell>alice@example.com</:cell>
    </.table_row>
    <.table_row>
      <:cell>Bob Johnson</:cell>
      <:cell>In Progress</:cell>
      <:cell>bob@example.com</:cell>
    </.table_row>
  </.table_body>
</.table>

Rich Content Table

<.table>
  <.table_head>
    <:col>Lead</:col>
    <:col>Stage</:col>
    <:col>Contact</:col>
    <:col></:col>
  </.table_head>
  <.table_body>
    <.table_row>
      <:cell class="w-full flex items-center gap-2">
        <img src="https://i.pravatar.cc/150?u=1" class="size-9 rounded-full" />
        <div class="flex flex-col gap-0.5">
          <span class="font-semibold">Sarah Johnson</span>
          <span class="text-zinc-400 text-sm/3">Product Manager</span>
        </div>
      </:cell>
      <:cell>
        <.badge color="green">Active</.badge>
      </:cell>
      <:cell>sarah.j@example.com</:cell>
      <:cell>
        <.icon name="hero-ellipsis-horizontal" class="size-5" />
      </:cell>
    </.table_row>
  </.table_body>
</.table>

Sortable Columns and Clickable Rows

<.table>
  <.table_head>
    <:col phx-click="sort" phx-value-column="name">
      <div class="flex items-center gap-1">
        Lead <.icon name="hero-chevron-up-down" class="size-4 text-zinc-500" />
      </div>
    </:col>
    <:col phx-click="sort" phx-value-column="stage">
      <div class="flex items-center gap-1">
        Stage <.icon name="hero-chevron-up-down" class="size-4 text-zinc-500" />
      </div>
    </:col>
  </.table_head>
  <.table_body>
    <.table_row>
      <:cell>John Smith</:cell>
      <:cell>New Lead</:cell>
    </.table_row>
  </.table_body>
</.table>

<.table>
  <.table_head>
    <:col>Customer</:col>
    <:col>Status</:col>
    <:col>Last Order</:col>
  </.table_head>

  <.table_body>
    <.table_row
      :for={customer <- @customers}
      class="cursor-pointer hover:bg-zinc-50"
      phx-click="show_customer"
      phx-value-id={customer.id}
    >
      <:cell>
        <div class="flex items-center gap-2">
          <img src={customer.avatar} class="size-8 rounded-full" />
          <span class="font-medium">{customer.name}</span>
        </div>
      </:cell>
      <:cell><.badge color="green">Active</.badge></:cell>
      <:cell>{customer.last_order_date}</:cell>
    </.table_row>
  </.table_body>
</.table>

Data Table with Actions

<.table>
  <.table_head>
    <:col>User</:col>
    <:col>Role</:col>
    <:col>Status</:col>
    <:col>Actions</:col>
  </.table_head>

  <.table_body>
    <.table_row :for={user <- @users}>
      <:cell>
        <div class="flex items-center gap-3">
          <img src={user.avatar} class="size-10 rounded-full" />
          <div>
            <div class="font-medium">{user.name}</div>
            <div class="text-sm text-zinc-500">{user.email}</div>
          </div>
        </div>
      </:cell>
      <:cell>
        <span class="inline-flex items-center rounded-full bg-blue-50 px-2 py-1 text-xs font-medium text-blue-700">
          {user.role}
        </span>
      </:cell>
      <:cell>
        <.badge color={if user.active, do: "green", else: "red"}>
          {if user.active, do: "Active", else: "Inactive"}
        </.badge>
      </:cell>
      <:cell>
        <div class="flex items-center gap-2">
          <.button size="sm" variant="ghost" phx-click="edit_user" phx-value-id={user.id}>
            Edit
          </.button>
          <.button size="sm" variant="ghost" color="danger" phx-click="delete_user" phx-value-id={user.id}>
            Delete
          </.button>
        </div>
      </:cell>
    </.table_row>
  </.table_body>
</.table>

Empty State Table

<.table>
  <.table_head>
    <:col>Name</:col>
    <:col>Email</:col>
    <:col>Status</:col>
  </.table_head>

  <.table_body>
    <.table_row :if={Enum.empty?(@users)}>
      <:cell colspan="3" class="text-center py-12 text-zinc-500">
        <div class="flex flex-col items-center gap-3">
          <.icon name="hero-users" class="size-12 text-zinc-300" />
          <div>
            <p class="text-sm font-medium">No users found</p>
            <p class="text-xs">Get started by creating your first user.</p>
          </div>
          <.button size="sm" phx-click="new_user">Add User</.button>
        </div>
      </:cell>
    </.table_row>

    <.table_row :for={user <- @users}>
      <:cell>{user.name}</:cell>
      <:cell>{user.email}</:cell>
      <:cell>{user.status}</:cell>
    </.table_row>
  </.table_body>
</.table>

Tabs

A tabs system for creating accessible, interactive tabbed interfaces with keyboard navigation support.

Components

• tabs: The main container providing structure and JavaScript functionality
• tabs_list: Navigation container holding the interactive tab buttons
• tabs_panel: Content panels associated with each tab, displayed one at a time

Attributes

tabs

• id (string): A unique identifier for the tabs container
• class (any, default: nil): Additional CSS classes for the tabs container
• rest (global): Additional HTML attributes

tabs_list

• class (any, default: nil): Additional CSS classes for the tablist container
• active_tab (string): The name of the tab that should be initially active
• variant (string, default: "default"): The visual style variant - "default", "segmented", "ghost"
• size (string, default: "md"): The size of the tabs container - "xs", "sm", "md"

tabs_panel

• name (string, required): The unique identifier for this panel
• class (any, default: nil): Additional CSS classes for the panel element
• active (boolean, default: false): Controls the visibility of the panel
• rest (global): Additional HTML attributes

Slots

tabs

• inner_block (required): Typically contains one tabs_list and one or more tabs_panel components

tabs_list

• tab (required): Defines an individual interactive tab button with required name attribute
• inner_block (required): Main content area containing the tab slots

tabs_panel

• inner_block (required): The content displayed when corresponding tab is active

Usage Examples

Basic Static Tabs

<.tabs id="my-tabs">
  <.tabs_list active_tab="settings">
    <:tab name="profile">Profile</:tab>
    <:tab name="settings">Settings</:tab>
    <:tab name="notifications">Notifications</:tab>
  </.tabs_list>

  <.tabs_panel name="profile">
    Profile content here...
  </.tabs_panel>

  <.tabs_panel name="settings" active>
    Settings content here...
  </.tabs_panel>

  <.tabs_panel name="notifications">
    Notifications content here...
  </.tabs_panel>
</.tabs>

Visual Variants and Sizes

<!-- Default underlined style -->
<.tabs_list variant="default">
  <:tab name="tab1">Default Tab</:tab>
</.tabs_list>

<!-- Segmented button-like style -->
<.tabs_list variant="segmented">
  <:tab name="tab1">Segmented Tab</:tab>
</.tabs_list>

<!-- Ghost style with subtle backgrounds -->
<.tabs_list variant="ghost">
  <:tab name="tab1">Ghost Tab</:tab>
</.tabs_list>

<!-- Size variants -->
<.tabs_list size="xs">
  <:tab name="tab1">Extra Small Tab</:tab>
</.tabs_list>

<.tabs_list size="sm">
  <:tab name="tab1">Small Tab</:tab>
</.tabs_list>

Rich Tab Content

<.tabs_list>
  <:tab name="messages">
    <.icon name="hero-envelope" class="icon" />
    Messages
    <.badge class="ml-2">3</.badge>
  </:tab>

  <:tab name="settings">
    <.icon name="hero-cog-6-tooth" class="icon" />
    Settings
  </:tab>
</.tabs_list>

LiveView Integration

<.tabs id="lv-sync-tabs">
  <.tabs_list active_tab={@active_tab}>
    <:tab name="profile" phx-click={JS.push("set_active_tab", value: %{tab: "profile"})}>
      Profile
    </:tab>
    <:tab name="settings" phx-click={JS.push("set_active_tab", value: %{tab: "settings"})}>
      Settings
    </:tab>
  </.tabs_list>

  <.tabs_panel name="profile" active={@active_tab == "profile"}>
    Profile content...
  </.tabs_panel>
  <.tabs_panel name="settings" active={@active_tab == "settings"}>
    Settings content...
  </.tabs_panel>
</.tabs>

Complex Form Tabs

<.tabs id="user-form-tabs">
  <.tabs_list active_tab={@active_tab} variant="segmented">
    <:tab name="basic" phx-click={JS.push("set_tab", value: %{tab: "basic"})}>
      <.icon name="hero-user" class="icon" />
      Basic Info
    </:tab>
    <:tab name="contact" phx-click={JS.push("set_tab", value: %{tab: "contact"})}>
      <.icon name="hero-envelope" class="icon" />
      Contact
    </:tab>
  </.tabs_list>

  <.tabs_panel name="basic" active={@active_tab == "basic"} class="space-y-4">
    <.input field={@form[:name]} label="Full Name" />
    <.input field={@form[:username]} label="Username" />
  </.tabs_panel>

  <.tabs_panel name="contact" active={@active_tab == "contact"} class="space-y-4">
    <.input field={@form[:email]} type="email" label="Email" />
    <.input field={@form[:phone]} label="Phone Number" />
  </.tabs_panel>
</.tabs>

Textarea

A versatile textarea component for capturing multi-line text input with form integration and size variants.

Attributes

• id (string, default: nil): The unique identifier for the textarea
• field (Phoenix.HTML.FormField): The form field to bind to
• class (any, default: nil): Additional CSS classes for the textarea
• help_text (string, default: nil): Optional help text displayed below the textarea
• label (string, default: nil): The primary label for the textarea
• sublabel (string, default: nil): Additional context beside the main label
• description (string, default: nil): Detailed description below the label
• value (string): The current value of the textarea
• errors (list, default: []): List of error messages
• name (string, required when not using field): The form name for the textarea
• rows (integer, default: 3): The number of visible text lines
• disabled (boolean, default: false): Disables the textarea
• size (string, default: "md"): Controls textarea size - "sm", "md", "lg", "xl"
• rest (global): Additional HTML attributes

Usage Examples

Basic Textarea and Size Variants

<.textarea
  name="description"
  label="Description"
  placeholder="Enter description..."
/>

<.textarea name="description" label="Small" size="sm" placeholder="A compact textarea" />
<.textarea name="description" label="Large" size="lg" placeholder="Larger textarea" />
<.textarea name="description" label="Extra Large" size="xl" placeholder="Maximum emphasis" />

With Labels and Form Integration

<.textarea
  name="bio"
  label="Biography"
  help_text="Tell us about yourself"
  rows={5}
/>

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <.textarea
    field={f[:description]}
    label="Description"
    help_text="Provide a detailed description of your project"
  />
</.form>

<.form :let={f} for={@form} phx-change="validate">
  <.textarea
    field={f[:description]}
    label="Project Description"
    sublabel="Optional"
    description="Provide details about your project's goals and scope"
    help_text="Be specific and concise"
    rows={6}
  />
</.form>

Custom Styling and States

<.textarea
  name="notes"
  label="Meeting Notes"
  size="lg"
  class="font-mono"
  rows={10}
/>

<.textarea
  name="readonly_field"
  label="Read Only Field"
  value="This content cannot be edited"
  disabled
/>

<.textarea
  name="content"
  label="Article Content"
  rows={15}
  maxlength={5000}
  placeholder="Write your article content here..."
  spellcheck="true"
/>

Rich Form Example

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <div class="space-y-6">
    <.textarea
      field={f[:summary]}
      label="Summary"
      sublabel="Required"
      rows={3}
      maxlength={500}
      help_text="Brief overview of the content"
    />

    <.textarea
      field={f[:content]}
      label="Full Content"
      description="The main body of your article or post"
      rows={12}
      help_text="Use markdown formatting if needed"
    />

    <.textarea
      field={f[:notes]}
      label="Internal Notes"
      sublabel="Optional"
      size="sm"
      rows={2}
      help_text="Private notes for internal use"
    />
  </div>

  <.button type="submit">Save Article</.button>
</.form>

Tooltip

A lightweight and accessible tooltip component for displaying informative content on hover or focus.

Attributes

• id (string, optional): Unique identifier for the tooltip
• value (string, optional): Text content for simple tooltips
• class (any, optional): Additional CSS classes for the tooltip container
• arrow (boolean, default: true): Whether to show the pointing arrow indicator
• placement (string, default: "top"): Tooltip position - "bottom", "left", "top", "right"
• delay (integer, default: 0): Delay in milliseconds before showing tooltip

Slots

• inner_block (required): The trigger element that shows tooltip on hover/focus
• content (optional): Rich content slot for complex tooltip content

Usage Examples

Basic and Rich Content

<.tooltip value="Opens in a new window">
  <.button>Open</.button>
</.tooltip>

<.tooltip>
  <.button>View details</.button>

  <:content>
    <div class="space-y-2">
      <img src="/images/preview.png" class="rounded-lg w-full" />
      <p class="text-sm">Preview of the document layout and structure.</p>
    </div>
  </:content>
</.tooltip>

Different Placements and Icon Tooltips

<div class="flex gap-4">
  <.tooltip value="Top placement" placement="top">
    <.button>Top</.button>
  </.tooltip>

  <.tooltip value="Right placement" placement="right">
    <.button>Right</.button>
  </.tooltip>
</div>

<div class="flex gap-2">
  <.tooltip value="Share">
    <.button variant="ghost"><.icon name="hero-share" /></.button>
  </.tooltip>

  <.tooltip value="Add to favorites">
    <.button variant="ghost"><.icon name="hero-star" /></.button>
  </.tooltip>
</div>

Form Field Help and Custom Styling

<div class="flex items-center gap-2">
  <.input type="text" name="api_key" value="">
    <:inner_suffix>
      <.tooltip value="Your API key can be found in the developer settings">
        <.icon name="hero-question-mark-circle" class="text-zinc-400" />
      </.tooltip>
    </:inner_suffix>
  </.input>
</div>

<.tooltip
  value="Draft saved"
  class="bg-green-600 text-white"
  arrow={false}
>
  <.badge>Draft</.badge>
</.tooltip>

<.tooltip value="Archived items are hidden from the main view" delay={300}>
  <.icon name="hero-archive" class="text-zinc-400" />
</.tooltip>

User Profile Preview

<.tooltip class="max-w-xs">
  <.link navigate={"/users/#{@user.id}"}>
    {@user.name}
  </.link>

  <:content>
    <div class="space-y-1">
      <p class="font-medium">{@user.name}</p>
      <p class="text-sm text-zinc-300">{@user.title}</p>
      <p class="text-sm text-zinc-300">{@user.department}</p>
    </div>
  </:content>
</.tooltip>