Settings PrimerLive.Component (PrimerLive v0.3.2)

status
Status

Feature complete.

form_group(assigns)

Generates a form group: a wrapper around one or more inputs. Automatically adds a label based on supplied form and field, with the option to set a custom label.

<.form_group field="first_name">
  <.text_input field="first_name" />
</.form_group>

examples
Examples

With a Phoenix.HTML.Form:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.form_group form={f} field={:first_name} autocomplete="off">
    <.text_input
      form={f}
      field={:first_name}
      phx_debounce="blur"
    />
  </.form_group>
</.form>

Custom label:

<.form_group form={f} field={:first_name} label="Enter your first name">
...
</.form_group>

Hide the label:

<.form_group form={f} field={:first_name} is_hide_label>
...
</.form_group>

attributes
Attributes

field (:any) - Field name (atom or string).
form (:any) - Either a Phoenix.HTML.Form or an atom.
label (:string) - Custom label. Note that a label is automatically generated when using field. Defaults to nil.
is_hide_label (:boolean) - Omits the label when using field. Defaults to false.
class (:string) - Additional classname. Defaults to nil.
for (:string) - Internally used by text_input/1 and textarea/1 when using is_form_group or form_group. Label attribute to associate the label with the input. for should be the same as the input's id. Defaults to nil.

classes (:map) - Additional classnames for form group elements.

Any provided value will be appended to the default classname.

Default map:

%{
  group: "",              # Form group element
  header: "",             # Header element containing the group label
  body: "",               # Input wrapper
  label: "",              # Form group label
}

Defaults to %{body: nil, group: nil, header: nil, label: nil, validation_message: nil}.

Global attributes are accepted.

slots
Slots

inner_block (required) - Form group content.

reference
Reference

status
Status

Feature complete.

input_validation_message(assigns)

Generates a validation message for a form input.

This component is incorporated in "singular inputs" text_input/1, textarea/1 and select/1. It can be used as standalone component for inputs where the position of the validation feedback is not so obvious.

A validation error message is automatically added when using a changeset with an error state. The message text is taken from the changeset errors.

To show the default validation message:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <!-- INPUTS -->
  <.input_validation_message form={@form} field={:availability} />
</.form>

To show a custom error message:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <!-- INPUTS -->
  <.input_validation_message
    form={@form}
    field={:availability}
    validation_message={
      fn field_state ->
        if !field_state.valid?, do: "Please select your availability"
      end
    }
  />
</.form>

Similarly, to show a custom validation success message:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <!-- INPUTS -->
  <.input_validation_message
    form={@form}
    field={:availability}
    validation_message={
      fn field_state ->
        if field_state.valid?, do: "Great!"
      end
    }
  />
</.form>

attributes
Attributes

class (:string) - Classname. Defaults to nil.
field (:any) - Field name (atom or string).
form (:any) - Either a Phoenix.HTML.Form or an atom.
validation_message (:any) - Function to write a custom validation message (in case of error or success). See text_input/1.
input_id (:string) - If the associated input has an id, pass it here as "input_id". Global attributes are accepted.

radio_button(assigns)

Generates a radio button.

Wrapper around Phoenix.HTML.Form.radio_button/4.

<.radio_button name="role" value="admin" />
<.radio_button name="role" value="editor" />

examples
Examples

Set the checked state:

<.radio_button name="role" value="admin" />
<.radio_button name="role" value="editor" checked />

Using the radio button with form data. This will automatically create the radio button label:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.radio_button form={f} field={:role} value="admin" />
  <.radio_button form={f} field={:role} value="editor" />
</.form>

Pass a custom radio button label with the label slot:

<.radio_button form={:user} field={:role}>
  <:label>Some label</:label>
</.radio_button>

Add emphasis to the label:

<.radio_button name="role" is_emphasised_label />

Add a hint below the label:

<.radio_button name="role">
  <:label>Some label</:label>
  <:hint>
    Add your <strong>resume</strong> below
  </:hint>
</.radio_button>

Reveal extra details when the radio button is checked:

<.radio_button name="role">
  <:label>Some label</:label>
  <:disclosure>
    <span class="d-block mb-1">Available hours per week</span>
    <.text_input is_contrast size="3" />
    <span class="text-small color-fg-muted pl-2">hours per week</span>
  </:disclosure>
</.radio_button>

attributes
Attributes

field (:any) - Field name (atom or string).
form (:any) - Either a Phoenix.HTML.Form or an atom.
name (:string) - Input name attribute (when not using form and field).
value (:string) - Input value. Defaults to nil.
checked (:boolean) - The state of the radio button (when not using form and field).
is_emphasised_label (:boolean) - Adds emphasis to the label. Defaults to false.
is_omit_label (:boolean) - Omits any label. Defaults to false.
class (:string) - Additional classname. Defaults to nil.

classes (:map) - Additional classnames for radio button elements.

Any provided value will be appended to the default classname.

Default map:

%{
  label: "",      # Input label
  input: "",      # Radio button input element
  hint: "",       # Hint message container
  disclosure: ""  # Disclosure container (inline)
}

Defaults to %{disclosure: nil, hint: nil, input: nil, label: nil}.

Global attributes are accepted.

slots
Slots

label - Custom radio button label. Overides the derived label when using a form and field. Accepts attributes:
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the label element.
hint - Adds text below the radio button label. Enabled when a label is displayed. Accepts attributes:
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the hint element.
disclosure - Extra label content to be revealed when the radio button is checked. Enabled when a label is displayed.Note that the label element can only contain inline child elements.Accepts attributes:
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the disclosure wrapper element.

reference
Reference

status
Status

Feature complete.

radio_group(assigns)

Groups radio buttons in a tab-like row.

Radio buttons are generated from the radio_button slot:

<.radio_group>
  <:radio_button name="role" value="admin"></:radio_button>
  <:radio_button name="role" value="editor"></:radio_button>
</.radio_group>

examples
Examples

Using a Phoenix.HTML.Form, attributes form and field are passed from radio group to the radio buttons, and labels are generated automatically:

<.form let={f} for={@changeset}>
  <.radio_group form={f} field={:role}>
    <:radio_button value="admin"></:radio_button>
    <:radio_button value="editor"></:radio_button>
  </.radio_group>
</.form>

Generates:

<form method="post" errors="">
  <div class="radio-group">
    <input class="radio-input" id="demo_user_role_admin"
      name="demo_user[role]" type="radio" value="admin">
    <label class="radio-label" for="demo_user_role_admin">Admin</label>
    <input class="radio-input" id="demo_user_role_editor"
      name="demo_user[role]" type="radio" value="editor">
    <label class="radio-label" for="demo_user_role_editor">Editor</label>
  </div>
</form>

Use custom label with the radio_button slot inner_block:

<.radio_group>
  <:radio_button name="role" value="admin">My role is Admin</:radio_button>
  <:radio_button name="role" value="editor">My role is Editor</:radio_button>
</.radio_group>

attributes
Attributes

field (:any) - Field name (atom or string).
form (:any) - Either a Phoenix.HTML.Form or an atom.
class (:string) - Additional classname. Defaults to nil.
classes (:map) - Additional classnames for radio group elements.
Any provided value will be appended to the default classname.
Default map:
```
%{
  radio_group: "", # Wrapper
  label: "",       # Radio button label
  radio_input: "", # Radio button input
}
```
Defaults to %{label: nil, radio_group: nil, radio_input: nil}.
id_prefix (:string) - Attribute id prefix to create unique ids. Defaults to nil. Global attributes are accepted.

slots
Slots

radio_button - Generates a radio button. Accepts attributes:
- value (:string) - See radio_button/1.
- name (:string) - See radio_button/1.
- checked (:boolean) - See radio_button/1.
- class (:string) - Additional classname.

reference
Reference

status
Status

Feature complete.

select(assigns)

Generates a single or multiple select input.

Wrapper around Phoenix.HTML.Form.select/4 and Phoenix.HTML.Form.multiple_select/4.

<.select name="age" options={25..35} />

examples
Examples

Options can contain:

A list:
- 25..35
- ["male", "female", "won't say"]
A keyword list:
- ["Admin": "admin", "User": "user"]
A nested keyword list with option attributes:
- [[key: "Admin", value: "admin", disabled: true], [key: "User", value: "user"]]

Create a small select input:

<.select name="age" options={25..35} is_small />

Set the selected item:

<.select name="age" options={25..35} selected="30" />

Add a prompt:

<.select name="age" options={25..35} prompt="Choose your age" />

Set attributes to the prompt option:

<.select
  name="age"
  options={25..35}
  prompt={[key: "Choose your age", disabled: true, selected: true]}
/>

Create a multiple select with is_multiple.

Use is_auto_height to set the height of the select input to the number of options.
From the Phoenix documentation: Values are expected to be an Enumerable containing two-item tuples (like maps and keyword lists) or any Enumerable where the element will be used both as key and value for the generated select.
selected should contain a list of selected options.

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.select
    form={f}
    field={:role}
    options={["Admin": "admin", "User": "user", "Editor": "editor"]}
    is_multiple
    is_auto_height
    selected={["user", "tester"]}
  />
</.form>

Place the select inside a form_group/1 with is_form_group. See text_input/1 for examples.

A validation error message is automatically added when using a changeset with an error state. See text_input/1 how to customise the validation messages.

attributes
Attributes

field (:any) - Field name (atom or string).
form (:any) - Either a Phoenix.HTML.Form or an atom.
name (:string) - Select name attribute (when not using form and field).
options (:any) (required) - Selectable options (list, map or keyword list).
selected (:any) - Selected option or options (string for single select, list when using is_multiple).
class (:string) - Additional classname.
classes (:map) - Additional classnames for select elements.
Any provided value will be appended to the default classname.
Default map:
```
%{
  select_container: "",   # Select container element
  select: "",             # Select element
  validation_message: "", # Validation message
}
```
Defaults to %{select: nil, select_container: nil, validation_message: nil}.
prompt (:any) - The default option that is displayed in the select options before the user makes a selection. See Phoenix.HTML.Form.multiple_select/4.
Can't be used with a multiple select - this attribute will be ignored.
Pass a string or a keyword list.
Examples:
```
<.select name="age" options={25..35} prompt="Choose your age" />
```
Set attributes to the prompt option:
```
<.select
  name="age"
  options={25..35}
  prompt={[key: "Choose your age", disabled: true, selected: true]}
/>
```
is_multiple (:boolean) - Creates a multiple select. Uses Phoenix.HTML.Form.multiple_select/4.
From the Phoenix documentation:
Values are expected to be an Enumerable containing two-item tuples (like maps and keyword lists) or any Enumerable where the element will be used both as key and value for the generated select.
Defaults to false.
is_small (:boolean) - Creates a small select. Defaults to false.
is_large (:boolean) - Creates a large select. Defaults to false.
is_short (:boolean) - Creates a short select. Defaults to false.
is_shorter (:boolean) - Creates a shorter select. Defaults to false.
is_full_width (:boolean) - Full width select. Defaults to false.
is_auto_height (:boolean) - When using is_multiple: sets the size to the number of options. Defaults to false.
is_monospace (:boolean) - Uses a monospace font. Defaults to false.
is_form_group (:boolean) - Inserts the select inside a form_group/1. Attributes form and field are passed to the form group to generate a group label.
To configure the form group and label, use attr form_group.
Defaults to false.
form_group (:any) - Form group attributes. Inserts the select inside a form_group/1 with given attributes, alongside form and field to generate a group label.
validation_message (:any) - Function to write a custom validation message (in case of error or success). See text_input/1. Global attributes are accepted.

reference
Reference

status
Status

Feature complete.

text_input(assigns)

Generates a text input field.

Wrapper around Phoenix.HTML.Form.text_input/3, optionally wrapped itself inside a "form group" to add a field label.

<.text_input field="first_name" />

examples
Examples

Set the input type:

<.text_input type="password" />
<.text_input type="hidden" />
<.text_input type="email" />

Set the placeholder. By default, the value of the placeholder attribute is used to fill in the aria-label attribute:

<.text_input placeholder="Enter your first name" />

Using the input with form data:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.text_input form={f} field={:first_name} />
  <.text_input form={f} field={:last_name} />
</.form>

Attach a button to the input with slot group_button:

<.text_input>
  <:group_button>
    <.button>Send</.button>
  </:group_button>
</.text_input>

or use an icon button:

<.text_input>
  <:group_button>
    <.button aria-label="Copy">
      <.octicon name="paste-16" />
    </.button>
  </:group_button>
</.text_input>

Add a button to the text input with slot trailing_action:

<.text_input>
  <:trailing_action>
    <.button is_icon_only aria-label="Clear">
      <.octicon name="x-16" />
    </.button>
  </:trailing_action>
</.text_input>

Only show the trailing action when the input has a value:

<.text_input>
  <:trailing_action is_visible_with_value>
    <.button is_icon_only aria-label="Clear">
      <.octicon name="x-16" />
    </.button>
  </:trailing_action>
</.text_input>

Add a leading visual with slot leading_visual:

<.text_input>
  <:leading_visual>
    <.octicon name="mail-16" />
  </:leading_visual>
</.text_input>

Place the input inside a form_group/1 with is_form_group. Attributes form and field are passed to the form group to generate a group label.

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.text_input form={f} field={:first_name} is_form_group />
</.form>

To configure the form group and label, use attr form_group. See form_group/1 for supported attributes.

A validation error message is automatically added when using a changeset with an error state. The message text is taken from the changeset errors. To show a custom validation error message, supply function validation_message:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.text_input
    form={f}
    field={:first_name}
    form_group={%{
      label: "Custom label",
      validation_message:
        fn field_state ->
          if !field_state.valid?, do: "Please enter your first name"
        end
    }}
  />
</.form>

Similarly, to show a custom validation success message:

<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.text_input
    form={f}
    field={:first_name}
    validation_message={
      fn field_state ->
        if field_state.valid?, do: "Available!"
      end
    }
  />
</.form>

attributes
Attributes

field (:any) - Field name (atom or string).
form (:any) - Either a Phoenix.HTML.Form or an atom.
class (:string) - Additional classname. Defaults to nil.

classes (:map) - Additional classnames for input elements.

Any provided value will be appended to the default classname.

Default map:

%{
  input: "",              # Input element
  input_group: "",        # Wrapper around the grouped input and group button
  input_group_button: "", # Wrapper around slot group_button
  validation_message: "", # Validation message
  input_wrap: "",         # Input wrapper when leading or trailing visual is used
}

Defaults to %{input: nil, input_group: nil, input_group_button: nil, input_wrap: nil, validation_message: nil}.

name (:string) - Text input name attribute (when not using form and field).
value (:string) - Text input value attribute (when not using form and field).
type (:string) - Text input type. Defaults to "text".
size (:any) - Defines the width of the input (number or number as string).
is_contrast (:boolean) - Changes the background color to light gray. Defaults to false.
is_full_width (:boolean) - Full width input. Defaults to false.
is_hide_webkit_autofill (:boolean) - Hide WebKit's contact info autofill icon. Defaults to false.
is_large (:boolean) - Additional padding creates a higher input box. If no width is specified, the input box is slightly wider. Defaults to false.
is_small (:boolean) - Smaller (less high) input with smaller text size. Defaults to false.
is_short (:boolean) - Inside a form group. Generates an input with a reduced width. Defaults to false.
is_shorter (:boolean) - Inside a form group. Generates an input with a even more reduced width. Defaults to false.
is_monospace (:boolean) - Uses a monospace font. Defaults to false.
is_form_group (:boolean) - Inserts the input inside a form_group/1. Attributes form and field are passed to the form group to generate a group label.
To configure the form group and label, use attr form_group.
Defaults to false.
form_group (:any) - Form group attributes. Inserts the input inside a form_group/1 with given attributes, alongside form and field to generate a group label.
validation_message (:any) - Function to write a custom validation message (in case of error or success).
The function receives a PrimerLive.FieldState struct and returns a validation message.
A validation message is shown:
- If form is a Phoenix.HTML.Form, containing a changeset
- And either:
  - changeset.action is :validate
  - validation_message returns a string
Function signature: fun field_state -> string | nil.
Example error message:
```
fn field_state ->
  if !field_state.valid?, do: "Please enter your first name"
end
```
Example success message, only shown when changeset.action is :validate:
```
fn field_state ->
  if field_state.valid? && field_state.changeset.action == :validate, do: "Is available"
end
```

Global attributes are accepted.

slots
Slots

group_button - Primer CSS "Input group". Attaches a button at the end of the input.

Example:

<.text_input>
  <:group_button>
    <.button aria-label="Copy">
      <.octicon name="paste-16" />
    </.button>
  </:group_button>
</.text_input>

leading_visual - Container for a leading visual. Commonly a octicon/1 component is used.
trailing_action - Container for a trailing action. Commonly a octicon/1 component, or a button/1 component with an icon (no label) is used. Accepts attributes:
- is_divider (:boolean) - Adds a separator line.
- is_visible_with_value (:boolean) - Only show the trailing action when the input has a value.
- class (:string) - Additional classname.

reference
Reference

status
Status

Feature complete.

textarea(assigns)

Generates a textarea.

<.textarea name="comments" />

attributes
Attributes

Use text_input/1 attributes.

reference
Reference

status
Status

Feature complete.

Link to this section Header

header(assigns)

Generates a navigational header, to be placed at the top of the page.

<.header>
  <:item>Item 1</:item>
  <:item>Item 2</:item>
  <:item>Item 3</:item>
</.header>

examples
Examples

Stretch an item with attribute is_full:

 <:item is_full>Stretched item</:item>

A space can also be generated with an "empty" item:

<:item is_full />

Links can be placed inside items. Use :let to get access to the classes.link class. With Phoenix.Component.link/1:

<:item :let={classes}>
  <.link href="/" class={classes.link}>Regular anchor link</.link>
</:item>
<:item :let={classes}>
  <.link navigate={Routes.page_path(@socket, :index)} class={[classes.link, "underline"]}>Home</.link>
</:item>

Inputs can be placed in the same way, using :let to get access to the classes.input class:

<:item :let={classes}>
  <.text_input form={:user} field={:first_name} type="search" class={classes.input} />
</:item>

attributes
Attributes

class (:string) - Additional classname.

classes (:map) - Additional classnames for header elements.

Any provided value will be appended to the default classname.

Default map:

%{
  header: "", # The wrapping element
  item: "",   # Header item element
  link: "",   # Link inside an item
  input: "",  # Input element inside an item
}

Defaults to %{header: nil, item: nil, link: nil}.

Global attributes are accepted.

slots
Slots

item - Header item. Accepts attributes:
- is_full (:boolean) - Stretches the item to maximum.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.

lets
Lets

<:item :let={classes} />

Yields a classes map, containing the merged values of default classnames, plus any value supplied to the classes component attribute.

<.header classes={%{ link: "link-x" }}>
  <:item :let={classes}>
    <.link href="/" class={["my-link", classes.link]}>Home</.link>
  </:item>
</.header>

Results in:

<div class="Header">
  <div class="Header-item">
    <a href="/" class="my-link Header-link link-x">Home</a>
  </div>
</div>

reference
Reference

Primer/CSS Header

status
Status

Feature complete.

Link to this section Icons

octicon(assigns)

Renders an icon from the set of GitHub icons, 512 including all size variations.

See PrimerLive.Octicons for the complete list.

<.octicon name="comment-16" />

examples
Examples

Pass the icon name with the size: icon "alert-fill" with size "12" becomes "alert-fill-12":

<.octicon name="alert-fill-12" />

Icon "pencil" with size 24:

<.octicon name="pencil-24" />

Custom class:

<.octicon name="pencil-24" class="app-icon" />

attributes
Attributes

name (:string) (required) - Icon name, e.g. "arrow-left-24". See available icons.
class (:string) - Additional classname. Global attributes are accepted.

reference
Reference

status
Status

Feature complete.

ui_icon(assigns)

Renders an interface icon.

These icons, while not part of the octicon/1 icons, are used in interface elements.

<.ui_icon name="single-select-16" />
<.ui_icon name="multiple-select-16" />
<.ui_icon name="collapse-16" />

attributes
Attributes

name (:string) (required) - Icon name, e.g. "single-select-16". Global attributes are accepted.

Link to this section Labels

counter(assigns)

Adds a count to navigational elements and buttons.

<.counter>12</.counter>

examples
Examples

Apply primary state:

<.counter is_primary>12</.counter>

With an icon:

<.counter><.octicon name="comment-16" /> 1.5K</.counter>

Add an emoji:

<.counter>👍 2</.counter>

attributes
Attributes

class (:string) - Additional classname.
is_primary (:boolean) - Primary color. Defaults to false.
is_secondary (:boolean) - Secondary color. Defaults to false. Global attributes are accepted.

slots
Slots

inner_block (required) - Label content.

reference
Reference

status
Status

Feature complete.

issue_label(assigns)

Issue labels are used for adding labels to issues and pull requests. They also come with emoji support.

And issue label is basically labels without a border. It expects background and foreground colors.

<.issue_label>Label</.issue_label>

examples
Examples

Add colors:

<.issue_label color-bg-accent-emphasis color-fg-on-emphasis>Label</.issue_label>

Larger label:

<.issue_label is_big>Label</.issue_label>

attributes
Attributes

class (:string) - Additional classname.
is_big (:boolean) - Larger issue label. Defaults to false. Global attributes are accepted.

slots
Slots

inner_block (required) - Label content.

reference
Reference

status
Status

Feature complete.

label(assigns)

Generates a label element.

Labels add metadata or indicate status of items and navigational elements.

<.label>Label</.label>

When using label alongside Phoenix.HTML.Form.label/2, use a prefix, for example:

use PrimerLive
alias PrimerLive.Component, as: P
...
<P.label>Label</P.label>

examples
Examples

Create a colored label:

<.label is_success>Label</.label>

Create a larger label:

<.label is_large>Label</.label>

Create an inline label:

<p>Lorem Ipsum is simply <.label is_inline>dummy text</.label> of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text.</p>

attributes
Attributes

class (:string) - Additional classname.
is_primary (:boolean) - Generates a label with a stronger border. Defaults to false.
is_secondary (:boolean) - Generates a label with a subtler text color. Defaults to false.
is_accent (:boolean) - Accent color. Defaults to false.
is_success (:boolean) - Success color. Defaults to false.
is_attention (:boolean) - Attention color. Defaults to false.
is_severe (:boolean) - Severe color. Defaults to false.
is_danger (:boolean) - Danger color. Defaults to false.
is_open (:boolean) - Open color. Defaults to false.
is_closed (:boolean) - Closed color. Defaults to false.
is_done (:boolean) - Done color. Defaults to false.
is_sponsors (:boolean) - Sponsors color. Defaults to false.
is_large (:boolean) - Larger label. Defaults to false.
is_inline (:boolean) - For use in running text. Adapts line height and font size to text. Defaults to false. Global attributes are accepted.

slots
Slots

inner_block (required) - Label content.

reference
Reference

status
Status

Feature complete.

state_label(assigns)

Shows an item's status.

State labels are larger and styled with bolded text. Attribute settings allows to apply colors.

<.state_label>Label</.state_label>

examples
Examples

Set a state (applying a background color):

<.state_label is_open>Label</.state_label>

Smaller label:

<.state_label is_small>Label</.state_label>

With an icon:

<.state_label is_open><.octicon name="git-pull-request-16" />Label</.state_label>

attributes
Attributes

class (:string) - Additional classname.
is_draft (:boolean) - Draft state color. Defaults to false.
is_open (:boolean) - Open state color. Defaults to false.
is_merged (:boolean) - Merged state color. Defaults to false.
is_closed (:boolean) - Closed state color. Defaults to false.
is_small (:boolean) - Smaller state label. Defaults to false. Global attributes are accepted.

slots
Slots

inner_block (required) - Label content.

reference
Reference

status
Status

Feature complete.

Link to this section Layout

layout(assigns)

Generates a responsive-friendly page layout with 2 columns.

<.layout>
  <:main>
    Main content
  </:main>
  <:sidebar>
    Sidebar content
  </:sidebar>
</.layout>

examples
Examples

The position of the sidebar (left or right on desktop) is set by CSS (and can be changed with attribute is_sidebar_position_end).

To place the sidebar at the right:

<.layout is_sidebar_position_end>
  <:main>
    Main content
  </:main>
  <:sidebar>
    Sidebar content
  </:sidebar>
</.layout>

To place the sidebar slot below the main slot on small screens, use attribute is_sidebar_position_flow_row_end:

<.layout is_sidebar_position_flow_row_end>
  <:main>
    Main content
  </:main>
  <:sidebar>
    Sidebar content
  </:sidebar>
</.layout>

When using a divider, use attribute is_divided to make the divider element visible.

Extra divider modifiers for vertical layout (on small screens):

is_divided creates a 1px border between main and sidebar
is_divided with is_flow_row_hidden hides the divider
is_divided with is_flow_row_shallow shows a filled 8px divider

<.layout is_divided>
  <:main>
    Main content
  </:main>
  <:divider></:divider>
  <:sidebar>
    Sidebar content
  </:sidebar>
</.layout>

The modifiers is_centered_xx create a wrapper around main to center its content up to a maximum width. Use with .container-xx classes to restrict the size of the content:

<.layout is_centered_md>
  <:main>
    <div class="container-md">
      Centered md
    </div>
  </:main>
  <:sidebar>
    Sidebar content
  </:sidebar>
</.layout>

Layouts can be nested.

Nested layout, example 1:

<.layout>
  <:main>
    <.layout is_sidebar_position_end is_narrow_sidebar>
      <:main>
        Main content
      </:main>
      <:sidebar>
        Metadata sidebar
      </:sidebar>
    </.layout>
  </:main>
  <:sidebar>
    Default sidebar
  </:sidebar>
</.layout>

Nested layout, example 2:

<.layout>
  <:main>
    <.layout is_sidebar_position_end is_flow_row_until_lg is_narrow_sidebar>
      <:main>
        Main content
      </:main>
      <:sidebar>
        Metadata sidebar
      </:sidebar>
    </.layout>
  </:main>
  <:sidebar>
    Default sidebar
  </:sidebar>
</.layout>

attributes
Attributes

class (:string) - Additional classname.

classes (:map) - Additional classnames for layout elements.

Any provided value will be appended to the default classname.

Default map:

  %{
    layout: "",               # Layout wrapper
    main: "",                 # Main element
    main_center_wrapper: "",  # Wrapper for displaying content centered
    sidebar: "",              # Sidebar element
    divider: "",              # Divider element
  }

Defaults to %{divider: nil, layout: nil, main: nil, main_center_wrapper: nil, sidebar: nil}.

is_divided (:boolean) - Use is_divided in conjunction with the layout_item/1 element with attribute divider to show a divider between the main content and the sidebar. Generates a 1px line between main and sidebar. Defaults to false.
is_narrow_sidebar (:boolean) - Smaller sidebar size. Widths: md: 240px, lg: 256px. Defaults to false.
is_wide_sidebar (:boolean) - Wider sidebar size. Widths: md: 296px, lg: 320px, xl: 344px. Defaults to false.
is_gutter_none (:boolean) - Changes the gutter size to 0px. Defaults to false.
is_gutter_condensed (:boolean) - Changes the gutter size to 16px. Defaults to false.
is_gutter_spacious (:boolean) - Changes the gutter sizes to: md: 16px, lg: 32px, xl: 40px. Defaults to false.
is_sidebar_position_start (:boolean) - Places the sidebar at the start (commonly at the left) (default). Defaults to false.
is_sidebar_position_end (:boolean) - Places the sidebar at the end (commonly at the right) on desktop. Defaults to false.
is_sidebar_position_flow_row_start (:boolean) - When stacked, render the sidebar first (default). Defaults to false.
is_sidebar_position_flow_row_end (:boolean) - When stacked, render the sidebar last. Defaults to false.
is_sidebar_position_flow_row_none (:boolean) - When stacked, hide the sidebar. Defaults to false.
is_flow_row_until_md (:boolean) - Stacks when container is md. Defaults to false.
is_flow_row_until_lg (:boolean) - Stacks when container is lg. Defaults to false.
is_centered_lg (:boolean) - Generates a wrapper around main to keep its content centered up to max width "lg". Defaults to false.
is_centered_md (:boolean) - Generates a wrapper around main to keep its content centered up to max width "md". Defaults to false.
is_centered_xl (:boolean) - Generates a wrapper around main to keep its content centered up to max width "xl". Defaults to false.
is_flow_row_hidden (:boolean) - On a small screen (up to 544px). Hides the horizontal divider. Defaults to false.
is_flow_row_shallow (:boolean) - On a small screen (up to 544px). Generates a filled 8px horizontal divider. Defaults to false. Global attributes are accepted.

slots
Slots

main - Generates a main element. Default gutter sizes: md: 16px, lg: 24px (change with is_gutter_none, is_gutter_condensed and is_gutter_spacious). Stacks when container is sm (change with is_flow_row_until_md and is_flow_row_until_lg). Accepts attributes:
- order (:any) - Markup order, defines in what order the slot is rendered in HTML. Keyboard navigation follows the markup order. Decide carefully how the focus order should be be by deciding whether main or sidebar comes first in code. The markup order won't affect the visual position. Default value: 2.Must be one of 1, 2, "1", or "2".
divider - Generates a divider element. The divider will only be shown with option is_divided. Generates a line between the main and sidebar elements - horizontal when the elements are stacked and vertical when they are shown side by side.
sidebar - Generates a sidebar element. Widths: md: 256px, lg: 296px (change with is_narrow_sidebar and is_wide_sidebar). Accepts attributes:
- order (:any) - See main slot. Default value: 1.Must be one of 1, 2, "1", or "2".

reference
Reference

Primer/CSS Layout

status
Status

Feature complete.

Link to this section Links

as_link(assigns)

Generates a consistent link-like appearance of actual links and spans inside links.

The component name deviates from the PrimerCSS name Link to prevent a naming conflict with Phoenix.Component.link/1.

Some text with a <.as_link>link</.as_link>

examples
Examples

links are created with Phoenix.Component.link/1. Link examples:

<.as_link href="/home">label</.as_link>
<.as_link navigate="/home">label</.as_link>
<.as_link patch="/home">label</.as_link>

Turn a link blue only on hover:

<.as_link href="/home" is_primary>link</.as_link>

Give it a muted gray color:

<.as_link href="/home" is_secondary>link</.as_link>

Turn a link blue only on hover:

<.as_link href="/home" is_primary>link</.as_link>

Rmove the underline:

<.as_link href="/home" is_no_underline>link</.as_link>

Use is_on_hover to make any text color used with links to turn blue on hover. This is useful when you want only part of a link to turn blue on hover. We are using a nested as_link for this:

<p>
  <.as_link href="#url" is_muted is_no_underline>
    A link with a partial <.as_link is_on_hover>hover link</.as_link>
  </.as_link>
</p>

Combine with color utility classes

<p>
  <.as_link href="#url" is_primary class="text-bold">
    <.octicon name="flame-16" width="12" class="color-fg-danger" />
    Hot <span class="color-fg-muted">potato</span>
  </.as_link>
</p>

attributes
Attributes

class (:string) - Additional classname. Defaults to nil.
is_primary (:boolean) - Turns the link color to blue only on hover. Defaults to false.
is_secondary (:boolean) - Turns the link color to blue only on hover, using a darker color. Defaults to false.
is_muted (:boolean) - Turns the link to muted gray, also on hover. Defaults to false.
is_no_underline (:boolean) - Removes the underline on hover. Defaults to false.
is_on_hover (:boolean) - Makes any text color used with links to turn blue on hover. This is useful when you want only part of a link to turn blue on hover. Defaults to false.
href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other attributes to the link.
patch (:string) - Link attribute - see href.
navigate (:string) - Link attribute - see href. Global attributes are accepted.

slots
Slots

inner_block (required) - Link content.

reference
Reference

Primer/CSS Links

status
Status

Feature complete.

Link to this section Loaders

animated_ellipsis(assigns)

Adds animated ellipsis to indicate progress.

<.animated_ellipsis />

examples
Examples

Inside a header:

<h2>Loading<.animated_ellipsis /></h2>

Inside a label:

<.label>Loading<.animated_ellipsis /></.label>

Inside a button:

<.button is_disabled>Loading<.animated_ellipsis /></.label>

attributes
Attributes

class (:string) - Additional classname. Defaults to nil. Global attributes are accepted.

reference
Reference

Primer/CSS Loaders

status
Status

Feature complete.

spinner(assigns)

SVG spinner animation.

This spinner is derived from the Toast loading animation.

<.spinner />

Alternatively, use octicon/1 with class "Toast--spinner", using any circular icon:

<.octicon name="skip-16" class="Toast--spinner" />

examples
Examples

Set the size (default: 18):

<.spinner size="40" />

Set the circle color (default: #959da5):

<.spinner color="red" />
<.spinner color="#ff0000" />
<.spinner color="rgba(250, 50, 150, 0.5)" />

Set the gap color (default: #ffffff):

<.spinner gap_color="black" />
<.spinner gap_color="#000000" />
<.spinner gap_color="rgba(0, 0, 0, 1)" />

attributes
Attributes

class (:string) - Additional classname. Defaults to nil.
size (:any) - Spinner size (number or number as string). Defaults to 18.
color (:string) - Spinner color as SVG fill color. Defaults to "#959da5".
gap_color (:string) - Spinner gap color as SVG fill color. Defaults to "#ffffff". Global attributes are accepted.

Link to this section Menus

action_list(assigns)

Action list is composed of one or more child components:

action_list_section_divider/1 - a divider with optional title
action_list_item/1 - versatile list item

See the Primer Action List interface guidelines for more examples.

examples
Examples

action_list
action_list

<.action_list>
  <.action_list_item>Item</.action_list_item>
  <.action_list_item>Item</.action_list_item>
</.action_list>

Create separator lines between the items:

<.action_list is_divided>
  ...
</.action_list>

Remove default padding:

<.action_list is_full_bleed>
  ...
</.action_list>

action_list_section_divider
action_list_section_divider

Add a divider to separate a group of content:

<.action_list>
  <.action_list_section_divider />
  ...
</.action_list>

Add a title to the divider, and optionally a description:

<.action_list>
  <.action_list_section_divider>
    <:title>Section title</:title>
    <:description>A descriptive text</:description>
  </.action_list_section_divider>
  ...
</.action_list>

Use the title slot to set the id for aria-labelledby:

<.action_list aria-labelledby="title-01">
  <.action_list_section_divider>
    <:title id="title-01">Section title</:title>
  </.action_list_section_divider>
  ...
</.action_list>

action_list_item
action_list_item

Common list item attributes:

<.action_list_item is_selected>
  This is the selected item
</.action_list_item>

<.action_list_item is_danger>
  Descructive item
</.action_list_item>

<.action_list_item is_disabled>
  Disabled item
</.action_list_item>

<.action_list_item is_button phx-click="remove">
  Button
</.action_list_item>

<.action_list_item is_height_medium>
  A higher item
</.action_list_item>

<.action_list_item is_height_large>
  An even higher item
</.action_list_item>

<.action_list_item is_truncated>
  A very long text that should stay on one line, abbreviated by ellipsis
</.action_list_item>

Use slot description to add a descriptive text. The description is displayed on a new line by default.

<.action_list_item>
  Short label
  <:description>
    A more descriptive text
  </:description>
</.action_list_item>

Place the description on the same line:

<.action_list_item is_inline_description>
  Short label
  <:description>
    A more descriptive text after the title
  </:description>
</.action_list_item>

Add a leading visual. This is usually an octicon/1, but can be any small image:

<.action_list_item>
  Item
  <:leading_visual>
    <.octicon name="bell-16" />
  </:leading_visual>
</.action_list_item>

Likewise, add a trailing visual:

<.action_list_item>
  Item
  <:leading_visual>
    <.counter>12</.counter>
  </:leading_visual>
</.action_list_item>

Items are by default rendered as span elements. To create link elements, place the label text inside slot link and pass attribute href, navigate or patch. When a link attribute is supplied to the link slot, links are created with Phoenix.Component.link/1, passing all other slot attributes to the link. Link examples:

<.action_list_item>
  <:link href="/url" target="_blank">
    href link
  </:link>
</.action_list_item>
<.action_list_item>
  <:link navigate={Routes.page_path(@socket, :index)}>
    navigate link
  </:link>
</.action_list_item>
<.action_list_item>
  <:link patch={Routes.page_path(@socket, :index)}>
    patch link
  </:link>
</.action_list_item>

Action list items can be selected. Single selections are represented with a check ui_icon/1, while multiple selections are represented with a checkbox ui_icon/1.

Create a single select list:

<.action_list>
  <.action_list_item is_single_select is_selected>
    Option
  </.action_list_item>
  <.action_list_item is_single_select>
    Option
  </.action_list_item>
  <.action_list_item is_single_select>
    Option
  </.action_list_item>
</.action_list>

Create a multiple select list. Add is_multiple_select to both action_list (for the proper ARIA attributes) and action_list_item (for leading visuals):

<.action_list is_multiple_select>
  <.action_list_item is_multiple_select is_selected>
    Option
  </.action_list_item>
  <.action_list_item is_multiple_select is_selected>
    Option
  </.action_list_item>
  <.action_list_item is_multiple_select>
    Option
  </.action_list_item>
</.action_list>

Deviating from the Primer implementation, selected items don't show a highlight border at the left. To give these items a navigation like appearance, use is_selected_link_marker:

<.action_list>
  <.action_list_item is_single_select is_selected_link_marker is_selected>
    Option
  </.action_list_item>
  <.action_list_item is_single_select is_selected_link_marker>
    Option
  </.action_list_item>
  <.action_list_item is_single_select is_selected_link_marker>
    Option
  </.action_list_item>
</.action_list>

Nested sub lists ("sub groups") can be used to initially hide additional options. A sub group is an action list placed inside a list item, which is automatically created by slot sub_group.

<.action_list>
  <.action_list_section_divider>
    <:title>Section title</:title>
  </.action_list_section_divider>
  <.action_list_item leading_visual_width="16" is_collapsible is_expanded>
    Collapsible and expanded item
    <:leading_visual>
      <.octicon name="comment-discussion-16" />
    </:leading_visual>
    <:sub_group>
      <.action_list_item is_sub_item>
        Sub item
      </.action_list_item>
      <.action_list_item is_sub_item>
        Sub item
      </.action_list_item>
    </:sub_group>
  </.action_list_item>
</.action_list>

slot sub_group accepts action_list/1 attributes
is_collapsible indicates that the sub group is conditionally hidden. The item is rendered as button.
is_expanded reveals hidden items.
leading_visual_width can be used to align the content with the visual.
action list attribute is_sub_item renders the item smaller.

When using a sub group, use the divider's title slot to set the id for aria-labelledby on the sub group:

<.action_list_section_divider>
  <:title id="title-01">Section title</:title>
</.action_list_section_divider>
<.action_list_item>
  Item
  <:sub_group aria-labelledby="title-01">
    ...
  </:sub_group>
</.action_list_item>

Example of using a form and event handler to submit a "single select" selection:

options = [
  %{id: "1", is_selected: true, label: "Writer"},
  %{id: "2", is_selected: false, label: "Programmer"},
  %{id: "3", is_selected: false, label: "Activist"}
]

...

<.form :let={f} for={@changeset} phx-change="save_user_job">
  <.action_list>
    <%= for %{id: id, label: label, is_selected: is_selected} <- @options do %>
      <.action_list_item
        is_single_select
        form={f}
        field={:job_id}
        checked_value={id}
        is_selected={is_selected}
      >
        <%= label %>
      </.action_list_item>
    <% end %>
  </.action_list>
</.form>

...

def handle_event("save_user_job", %{"user" => params}, socket) do
  %{user: user} = socket.assigns
  current_job_id = get_in(user.job, [Access.key!(:id)])

  selected_job_ids = params["job_id"] |> Enum.filter(&(&1 !== "false" && &1 !== current_job_id))
  job_id = if Enum.count(selected_job_ids) > 0, do: hd(selected_job_ids), else: nil

  changeset = User.changeset(socket.assigns.user, %{"job_id" => job_id})

  # apply changeset and assign user to socket
  ...
end

attributes
Attributes

aria_label (:string) - Adds attribute aria-label to the outer element. Defaults to nil.
role (:string) - Adds attribute role to the outer element. Defaults to "listbox".
class (:string) - Additional classname. Defaults to nil.
is_divided (:boolean) - Show dividers between items. Defaults to false.
is_full_bleed (:boolean) - Removes the default padding. Defaults to false.
is_multiple_select (:boolean) - Sets ARIA attribute and classes for multi select checkmarks. Defaults to false. Global attributes are accepted.

slots
Slots

inner_block (required) - Action list components.

reference
Reference

Primer/CSS Action List

status
Status

Feature complete.

action_list_item(assigns)

Action list item. See action_list/1.

attributes
Attributes

field (:any) - Field name (atom or string).
form (:any) - Either a Phoenix.HTML.Form or an atom.
checked_value (:string) - Checkbox checked_value, see checkbox/1. Defaults to nil.
class (:string) - Additional classname. Defaults to nil.

classes (:map) - Additional classnames for section item elements.

Any provided value will be appended to the default classname.

Default map:

%{
  action_list_item: "",          # Action list item element (li)
  content: "",                   # Content wrapper (span, a or button)
  label: "",                     # Label container (span)
  description: "",               # Description container (span)
  description_container: "",     # Container around label and description (span)
  leading_visual: "",            # Leading visual container (span)
  trailing_visual: "",           # Trailing visual container (span)
  sub_group: "",                 # Nested action_list
}

Defaults to %{content: nil, description: nil, description_container: nil, label: nil, leading_visual: nil, section_divider: nil, sub_group: nil, trailing_visual: nil}.

is_selected (:boolean) - Shows the selected state.
- Link items show an active border at the left and a gray highlighted background
- Single select items show a check icon
- Multiple select items show a selected checkbox icon
Defaults to false.
is_selected_link_marker (:boolean) - When using is_single_select or is_multiple_select: creates a selected state similar for selected link items (border and background). Defaults to false.
is_inline_description (:boolean) - Renders the description inline, on the same line as the label. Defaults to false.
is_height_medium (:boolean) - Sets the row height to at least 40px. The default row height is 32px (on touch devices this is 48px). Defaults to false.
is_height_large (:boolean) - Sets the row height to at least 48px. The default row height is 32px (on touch devices this is 48px as well). Defaults to false.
is_single_select (:boolean) - Creates a checkbox group, visualized as checkmark icons, and sets ARIA attributes. The icons can be replaced with the leading_visual slot. Defaults to false.
is_multiple_select (:boolean) - Creates a checkbox group, using smaller sized checkboxes, and sets ARIA attributes. The icons can be replaced with the leading_visual slot. Defaults to false.
is_checkmark_icon (:boolean) - Overrides the default leading_visual when using is_multiple_select. Visualizes the checkboxes as checkmark icons. Defaults to false.
is_button (:boolean) - Renders the content element with a button tag. Defaults to false.
is_collapsible (:boolean) - Inserts a collapse icon as trailing visual (override the visual by using trailing_visual slot). Use with is_expanded and sets ARIA attributes. Uses a button element instead of span.
When using slot sub_group, a false value of is_expanded will hide the sub group items.
Defaults to false.
is_expanded (:boolean) - Use with is_collapsible. Sets the state of the collapsible by setting ARIA attributes.
When using slot sub_group, a false value of is_expanded will hide the sub group items; a true value will show the items and make the current item bold.
Defaults to false.
is_danger (:boolean) - Adds a "danger" style to show that the item is descrucive. Defaults to false.
is_disabled (:boolean) - Shows the item is disabled. Defaults to false.
is_truncated (:boolean) - Shortens the item label with ellipsis. Defaults to false.
is_sub_item (:boolean) - For items within a sub_group. Renders the item smaller. Defaults to false.
leading_visual_width (:any) - Use with the item that contains slots sub_group and leading_visual. Indents the items within the sub group to match the leading visual.
Supported sizes: 16, 20, 24.

Global attributes are accepted.

slots
Slots

inner_block (required) - Label.
link - Creates a link. Pass attribute href, navigate or patch. Accepts attributes:
- href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other slot attributes to the link.
- patch (:string) - Link attribute - see href.
- navigate (:string) - Link attribute - see href.
- target (:string) - Link target.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the link element.
description - Description.
leading_visual - Container for a leading visual. Commonly a octicon/1 component is used.
The container's width is determined by the content. Use the same size icons and graphics for consistency. A common icon size is 16px.
trailing_visual - Container for a trailing visual. Commonly a octicon/1 component is used, but a textual "visual" is also possible.
sub_group - Creates a nested action_list/1. Pass action_list_items as children.
Use is_sub_item for child items to render them smaller.
Accepts attributes:
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the action list element.

action_list_section_divider(assigns)

Action list section divider for separating groups of content. See action_list/1.

attributes
Attributes

class (:string) - Additional classname. Defaults to nil.
classes (:map) - Additional classnames for section divider elements.
Any provided value will be appended to the default classname.
Default map:
```
%{
  section_divider: "", # Section divider element (li)
  title: "",           # Title container (h3)
  description: "",     # Description container (span)
}
```
Defaults to %{description: nil, section_divider: nil, title: nil}.
is_filled (:boolean) - Creates a higher horizontal line. When used with the title slot, the title is placed inside the line. Defaults to false. Global attributes are accepted.

slots
Slots

title - Title separator. The input text is wrapped in a <h3> element. Omit to create a horizontal line only. Accepts attributes:
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the action list element.
description - Optional extra text. Requires title slot. Accepts attributes:
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the action list element.

action_menu(assigns)

Generates an action menu.

The action menu functions similarly to a select_menu/1, but with an action_list/1 as content.

<.action_menu>
  <:toggle>Menu</:toggle>
  <.action_list>
    ...
  </.action_list>
</.action_menu>

examples
Examples

Create a multiple select menu:

<.action_menu is_dropdown_caret>
  <:toggle>Select <.counter>2</.counter></:toggle>
  <.action_list>
    <.action_list_item is_multiple_select is_selected>
      Option
    </.action_list_item>
    <.action_list_item is_multiple_select is_selected>
      Option
    </.action_list_item>
    <.action_list_item is_multiple_select>
      Option
    </.action_list_item>
  </.action_list>
</.action_menu>

See for more examples:

Action list examples
Select menu examples

attributes
Attributes

is_dropdown_caret (:boolean) - Adds a dropdown caret to the button. Defaults to false.
is_right_aligned (:boolean) - Aligns the menu to the right. Defaults to false.
class (:string) - Additional classname.

classes (:map) - Additional classnames for action menu elements.

Any provided value will be appended to the default classname, except for toggle that will override the default class "btn".

Default map:

%{
  action_menu: "",         # Action menu container (details element).
  caret: "",               # Dropdown caret element.
  menu_container: "",      # Menu container (called "modal" at PrimerCSS).
  menu_list: "",           # Menu list container.
  menu: "",                # Menu element
  toggle: "",              # Toggle element. Any value will override the
                           # default class "btn".
}

Defaults to %{action_menu: nil, caret: nil, menu: nil, menu_container: nil, menu_list: nil, toggle: nil}.

is_backdrop (:boolean) - Generates a light backdrop background color. Defaults to false.
is_dark_backdrop (:boolean) - Generates a darker backdrop background color. Defaults to false.
is_medium_backdrop (:boolean) - Generates a medium backdrop background color. Defaults to false.
is_light_backdrop (:boolean) - Generates a lighter backdrop background color (default). Defaults to false.
is_fast (:boolean) - Generates fast fade transitions for backdrop and content. Defaults to true.

menu_theme (:map) - Sets the theme of the menu, including the dropdown shadow, but excluding the toggle button. This is useful when the button resides in a part with a different theme, such as a dark header.

Pass a a map with all theme state keys. See theme/1.

Example:

<.header>
  <.action_menu menu_theme={@theme_state}>
    <:toggle>
      <.octicon name="sun-16" />
    </:toggle>
    <.theme_menu_options
      default_theme_state={@default_theme_state}
      theme_state={@theme_state}
    />
  </.action_menu>
<./header>

Defaults to nil.

Global attributes are accepted.

slots
Slots

toggle (required) - Generates a toggle element (default with button appearance) using the slot content as label.Any custom class will override the default class "btn".Accepts attributes:
- options (:string) - Toggle options as string. For example:
```
<:toggle options="{
  willShow: function(elements) { /* */ }
  didShow: function(elements) { /* */ }
  willHide: function(elements) { /* */ }
  didHide: function(elements) { /* */ }
  getStatus: function(status) { /* */ }
}">Menu</:toggle>
```
  See also: See: https://github.com/ArthurClemens/dialogic-js#prompttoggle
  To keep the action menu open while interacting with its content, you can use willHide or didHide to initiate a form submit:
```
<.action_menu>
  <:toggle options="{
    willHide: function(elements) {
      elements.root.querySelector('form')
        .dispatchEvent(new Event('submit', {bubbles: true, cancelable: true}));
    }
  }">Menu</:toggle>
  <.form :let={f} for={@changeset} phx-submit="save_user">
    ...
  </.form>
</.action_menu>
```
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.
inner_block - Slot to place the action_list/1 component.

reference
Reference

status
Status

Feature complete.

dropdown(assigns)

Generates a dropdown menu.

Dropdowns are small context menus that can be used for navigation and actions. They are a simple alternative to select menus.

Menu items are rendered as link element.

<.dropdown>
  <:toggle>Menu</:toggle>
  <:item href="#url">Item 1</:item>
  <:item href="#url">Item 2</:item>
</.dropdown>

Menu links are created with Phoenix.Component.link/1, passing all other slot attributes to the link. Link examples:

<:item href="#url">href link</:item>
<:item navigate={Routes.page_path(@socket, :index)}>navigate link</:item>
<:item patch={Routes.page_path(@socket, :index)}>patch link</:item>

Add a menu title by passing title to the menu slot:

<.dropdown>
  <:toggle>Menu</:toggle>
  <:menu title="Menu title" />
  ...
</.dropdown>

Change the position of the menu relative to the dropdown toggle:

<:menu position="e" />

Create dividers with item slot attribute is_divider. A divider cannot have contents.

<.dropdown>
  <:toggle>Menu</:toggle>
  ...
  <:item is_divider />
  ...
</.dropdown>

class (:string) - Additional classname. Defaults to nil.

classes (:map) - Additional classnames for dropdown elements.

Any provided value will be appended to the default classname, except for toggle that will override the default class "btn".

Default map:

%{
  caret: "",    # Arrow in toggle button
  divider: "",  # List divider item (li element)
  dropdown: "", # Dropdown wrapper
  header: "",   # Menu header
  item: "",     # Link item, placed inside li element
  menu: "",     # List container (ul element)
  toggle: ""    # Toggle (open) button
}

Defaults to %{caret: nil, divider: nil, dropdown: nil, header: nil, item: nil, menu: nil, toggle: nil}.

Global attributes are accepted.

toggle (required) - Generates a toggle element (default with button appearance) using the slot content as label.
Any custom class will override the default class "btn".
Accepts attributes:
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the toggle element.
menu - Generates a menu element. Accepts attributes:
- title (:string) - Generates a menu header with specified title.
- position (:string) - Position of the menu relative to the dropdown toggle.
  Default: "se".

Must be one of "se", "ne", "e", "sw", "s", or "w".

item (required) - Menu item content. To create a link element, pass attribute href, navigate or patch. Accepts attributes:
- is_divider (:boolean) - Generates a divider element.
- href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other slot attributes to the link.
- patch (:string) - Link attribute - see href.
- navigate (:string) - Link attribute - see href.
- phx_click (:string) - See https://hexdocs.pm/phoenix_live_view/bindings.html.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.

Primer/CSS Dropdown

Feature complete.

select_menu(assigns)

Generates a select menu.

<.select_menu>
  <:toggle>Menu</:toggle>
  <:item>Item 1</:item>
  <:item>Item 2</:item>
  <:item>Item 3</:item>
</.select_menu>

examples
Examples

When a link attribute is supplied to the item slot, links are created with Phoenix.Component.link/1, passing all other slot attributes to the link. Link examples:

<:item href="#url">href link</:item>
<:item navigate={Routes.page_path(@socket, :index)}>navigate link</:item>
<:item patch={Routes.page_path(@socket, :index)}>patch link</:item>

Add a dropdown caret:

<.select_menu is_dropdown_caret>
  ...
</.select_menu>

Add dividers, with or without content:

<.select_menu>
  <:toggle>Menu</:toggle>
  <:item>Item 1</:item>
  <:item is_divider />
  <:item>Item 2</:item>
  <:item is_divider>Divider content</:item>
  <:item>Item 3</:item>
</.select_menu>

Selected state. When any item is selected, all other items will line up nicely:

<.select_menu>
  <:toggle>Menu</:toggle>
  <:item is_selected>Selected</:item>
  <:item>Not selected</:item>
</.select_menu>

Add a menu title. The title is placed in a header row with a close button. The click target for the button is based on the id attribute (generated automatically if not supplied).

<.select_menu id="this-id-is-optional">
  <:toggle>Menu</:toggle>
  <:menu title="Title" />
  ...
</.select_menu>

Add a message:

<.select_menu>
  <:toggle>Menu</:toggle>
  <:message class="color-bg-danger color-fg-danger">Message</:message>
  ...
</.select_menu>

Add a filter input:

 <.select_menu>
  <:toggle>Menu</:toggle>
  <:filter>
    <form>
      <.text_input class="SelectMenu-input" type="search" name="q" placeholder="Filter" />
    </form>
  </:filter>
  ...
</.select_menu>

Add a tab menu filter by using slot tab:

 <.select_menu>
  <:toggle>Menu</:toggle>
  <:tab is_selected>
    Selected
  </:tab>
  <:tab>
    Other tab
  </:tab>
  ...
</.select_menu>

Add a footer:

<.select_menu>
  <:toggle>Menu</:toggle>
  ...
  <:footer>Footer</:footer>
</.select_menu>

attributes
Attributes

is_dropdown_caret (:boolean) - Adds a dropdown caret to the button. Defaults to false.
is_right_aligned (:boolean) - Aligns the menu to the right. Defaults to false.
is_borderless (:boolean) - Removes the borders between list items. Defaults to false.
class (:string) - Additional classname.

classes (:map) - Additional classnames for select menu elements.

Any provided value will be appended to the default classname, except for toggle that will override the default class "btn".

Default map:

%{
  blankslate: "",          # Blankslate content element.
  caret: "",               # Dropdown caret element.
  divider: "",             # Divider item element.
  filter: "",              # Filter content element
  footer: "",              # Footer element.
  header_close_button: "", # Close button in the header.
  header: "",              # Header element.
  item: "",                # Item element.
  loading: "",             # Loading content element.
  menu_container: "",      # Menu container (called "modal" at PrimerCSS).
  menu_list: "",           # Menu list container.
  menu_title: "",          # Menu title.
  menu: "",                # Menu element
  message: "",             # Message element.
  select_menu: "",         # Select menu container (details element).
  tabs: "",                # Tab container.
  tab: "",                 # Tab button.
  toggle: "",              # Toggle element. Any value will override the
                           # default class "btn".
}

Defaults to %{blankslate: nil, caret: nil, divider: nil, filter: nil, footer: nil, header: nil, header_close_button: nil, item: nil, loading: nil, menu: nil, menu_container: nil, menu_list: nil, menu_title: nil, message: nil, select_menu: nil, tab: nil, tabs: nil, toggle: nil}.

is_backdrop (:boolean) - Generates a light backdrop background color. Defaults to false.
is_dark_backdrop (:boolean) - Generates a darker backdrop background color. Defaults to false.
is_medium_backdrop (:boolean) - Generates a medium backdrop background color. Defaults to false.
is_light_backdrop (:boolean) - Generates a lighter backdrop background color (default). Defaults to false.
is_fast (:boolean) - Generates fast fade transitions for backdrop and content. Defaults to true. Global attributes are accepted.

slots
Slots

toggle (required) - Generates a toggle element (default with button appearance) using the slot content as label.
Any custom class will override the default class "btn".
Accepts attributes:
- options (:string) - Toggle options as string. For example:
```
<:toggle options="{
  willShow: function(elements) { /* */ }
  didShow: function(elements) { /* */ }
  willHide: function(elements) { /* */ }
  didHide: function(elements) { /* */ }
  getStatus: function(status) { /* */ }
}">Menu</:toggle>
```
  See also: https://github.com/ArthurClemens/dialogic-js#prompttoggle
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.
menu - Generates a menu element. Accepts attributes:
- title (:string) - Generates a menu header with specified title.
filter - Filter slot to insert a text_input/1 component that will drive a custom filter function.
tab - Tab item element. If a tab slot is used, a tab navigation will be generated containing button elements. Accepts attributes:
- is_selected (:boolean) - The currently selected tab.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the tab element.
footer - Footer content.
message - Message container. Use utility classes to further style the message.
Example:
```
<:message class="color-bg-danger color-fg-danger">Message</:message>
```
Accepts attributes:
- class (:string) - Additional classname.

loading - Slot to show a loading animation.

Example:

<:loading><.octicon name="copilot-48" class="anim-pulse" /></:loading>

blankslate - Slot to show blankslate content.
item - Menu item content. To create a link element, pass attribute href, navigate or patch. Accepts attributes:
- is_selected (:boolean) - Shows the selected state with a checkmark.
- is_disabled (:boolean) - Generates a disabled state.
- is_divider (:boolean) - Generates a divider. The divider may have content, for example a label "More options".
- selected_octicon_name (:boolean) - The icon name for the selected state, for example "check-circle-fill-16".
  Default "check-16".
- href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other slot attributes to the link.
- patch (:string) - Link attribute - see href.
- navigate (:string) - Link attribute - see href.
- phx_click (:string) - See https://hexdocs.pm/phoenix_live_view/bindings.html.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.

reference
Reference

Primer/CSS Select menu

status
Status

Feature complete.

Link to this section Navigation

filter_list(assigns)

Generates a vertical list of filters.

Filter list items are rendered as link element.

<.filter_list aria_label="Menu">
  <:item href="#url" is_selected>
    One
  </:item>
  <:item href="#url">
    Two
  </:item>
  <:item href="#url">
    Three
  </:item>
</.filter_list>

Filter links are created with Phoenix.Component.link/1, passing all other slot attributes to the link. Link examples:

<:item href="#url">href link</:item>
<:item navigate={Routes.page_path(@socket, :index)}>navigate link</:item>
<:item patch={Routes.page_path(@socket, :index)}>patch link</:item>

Add counts to the links:

<.filter_list aria_label="Menu">
  <:item href="#url" is_selected count="99">
    First filter
  </:item>
  <:item href="#url" count={3}>
    Second filter
  </:item>
  <:item href="#url">
    Third filter
  </:item>
</.filter_list>

class (:string) - Additional classname. Defaults to nil.

classes (:map) - Additional classnames for filter list elements.

Any provided value will be appended to the default classname.

Default map:

%{
  filter_list: "", # Outer container (ul element)
  item: "",        # Filter list item element (a element)
  count: "",       # Filter list item count element (span element)
}

Defaults to %{count: nil, filter_list: nil, item: nil}.

aria_label (:string) - Adds attribute aria-label to the outer element. Defaults to nil. Global attributes are accepted.

item (required) - Filter list item content. To create a link element, pass attribute href, navigate or patch. Accepts attributes:
- is_selected (:boolean) - Shows the selected state.
- count (:any) - Integer or string. Displays a number at the far end of the filter link.
- href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other slot attributes to the link.
- patch (:string) - Link attribute - see href.
- navigate (:string) - Link attribute - see href.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.

Feature complete.

menu(assigns)

Generates a vertical list of navigational links.

Menu items are rendered as link element.

<.menu aria_label="Site navigation">
  <:item href="#url" is_selected>
    Account
  </:item>
  <:item href="#url">
    Emails
  </:item>
</.menu>

examples
Examples

Menu links are created with Phoenix.Component.link/1, passing all other slot attributes to the link. Link examples:

<:item href="#url">href link</:item>
<:item navigate={Routes.page_path(@socket, :index)}>navigate link</:item>
<:item patch={Routes.page_path(@socket, :index)}>patch link</:item>

Add other types of content, such as icons and counters:

<.menu>
  <:item href="#url" is_selected>
    <.octicon name="comment-discussion-16" />
    <span>Conversation</span>
    <.counter>2</.counter>
  </:item>
  <:item href="#url">
    <.octicon name="check-circle-16" />
    <span>Done</span>
    <.counter>99</.counter>
  </:item>
</.menu>

Add a heading:

<.menu aria_label="Site navigation">
  <:heading>Menu heading</:heading>
  <:item href="#url" is_selected>
    Account
  </:item>
  <:item href="#url">
    Emails
  </:item>
</.menu>

attributes
Attributes

class (:string) - Additional classname. Defaults to nil.
classes (:map) - Additional classnames for underline nav elements.
Any provided value will be appended to the default classname.
Default map:
```
%{
  menu: "",    # Outer container (nav element)
  item: "",    # Menu item element
  heading: "", # Heading element
}
```
Defaults to %{heading: nil, item: nil, menu: nil}.
aria_label (:string) - Adds attribute aria-label to the outer element. Defaults to nil. Global attributes are accepted.

slots
Slots

item (required) - Menu content. To create a link element, pass attribute href, navigate or patch. Accepts attributes:
- is_selected (:boolean) - Shows the selected state.
- href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other slot attributes to the link.
- patch (:string) - Link attribute - see href.
- navigate (:string) - Link attribute - see href.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.
heading - Menu heading.

reference
Reference

status
Status

Feature complete.

side_nav(assigns)

Generates a vertical list of navigational links.

Menu items are rendered as link element.

<.side_nav aria_label="Site navigation">
  <:item href="#url" is_selected>
    Account
  </:item>
  <:item href="#url">
    Emails
  </:item>
</.side_nav>

examples
Examples

Menu links are created with Phoenix.Component.link/1, passing all other slot attributes to the link. Link examples:

<:item href="#url">href link</:item>
<:item navigate={Routes.page_path(@socket, :index)}>navigate link</:item>
<:item patch={Routes.page_path(@socket, :index)}>patch link</:item>

Add other types of content, such as icons and counters:

<.side_nav>
  <:item href="#url" is_selected>
    <.octicon name="comment-discussion-16" />
    <span>Conversation</span>
    <.counter>2</.counter>
  </:item>
  <:item href="#url">
    <.octicon name="check-circle-16" />
    <span>Done</span>
    <.counter>99</.counter>
  </:item>
  <:item href="#url">
    <h5>With a heading</h5>
    <span>and some longer description</span>
  </:item>
</.side_nav>

Add a border (not for sub navigation):

<.side_nav is_border>
  ...
</.side_nav>

Create a sub navigation: a lightweight version without borders and more condensed.

<.side_nav is_sub_nav>
  ...
</.side_nav>

A sub navigation can be placed inside a side navigation, using an item slot without attributes:

<.side_nav is_border>
  <:item href="#url">
    Item 1
  </:item>
  <:item navigate="#url" is_selected>
    Item 2
  </:item>
  <:item>
    <.side_nav is_sub_nav class="border-top py-3" style="padding-left: 16px">
      <:item href="#url" is_selected>
        Sub item 1
      </:item>
      <:item navigate="#url">
        Sub item 2
      </:item>
    </.side_nav>
  </:item>
  <:item navigate="#url">
    Item 3
  </:item>
</.side_nav>

attributes
Attributes

class (:string) - Additional classname. Defaults to nil.
classes (:map) - Additional classnames for underline nav elements.
Any provided value will be appended to the default classname.
Default map:
```
%{
  side_nav: "", # Outer container (nav element)
  item: "",     # Menu item element
  sub_item: "", # Menu sub item element
}
```
Defaults to %{item: nil, side_nav: nil, sub_item: nil}.
aria_label (:string) - Adds attribute aria-label to the outer element. Defaults to nil.
is_border (:boolean) - Adds a border. Not applied when using is_sub_nav. Defaults to false.
is_sub_nav (:boolean) - Sets the menu style to "sub navigation": a lightweight version without borders and more condensed. Defaults to false. Global attributes are accepted.

slots
Slots

item (required) - Menu content. To create a link element, pass attribute href, navigate or patch. Accepts attributes:
- is_selected (:boolean) - Shows the selected state.
- href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other slot attributes to the link.
- patch (:string) - Link attribute - see href.
- navigate (:string) - Link attribute - see href.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.

reference
Reference

status
Status

Feature complete.

subnav(assigns)

Subnav is navigation that is typically used when on a dashboard type interface with another set of navigation above it. This helps distinguish navigation hierarchy

Subnav is composed of one or more child components:

subnav_links/1 - a link row
subnav_search/1 - a search field
subnav_search_context/1 - a search filter menu adjacent to the search field

Minimal version, showing the link row:

<.subnav>
  <.subnav_links>
    <:item href="#url" is_selected>Item 1</:item>
    <:item href="#url">Item 2</:item>
    <:item href="#url">Item 3</:item>
  </.subnav_links>
</.subnav>

examples
Examples

subnav_links
subnav_links

To show a link row, use child component subnav_links/1.

Navigation links are created with Phoenix.Component.link/1, passing all other slot attributes to the link. Link examples:

<:item href="#url">href link</:item>
<:item navigate={Routes.page_path(@socket, :index)}>navigate link</:item>
<:item patch={Routes.page_path(@socket, :index)}>patch link</:item>

subnav_search
subnav_search

To add a search field, use child component subnav_search/1 with a text_input/1 component. Use type="search" to display a search icon inside the search field.

<.subnav>
  <.subnav_search>
    <.text_input type="search" />
  </.subnav_search>
</.subnav>

subnav_search_context
subnav_search_context

To place a filter menu adjacent to the search field, use child component subnav_search_context/1 with a select_menu/1 component:

<.subnav>
  <.subnav_search_context>
    <.select_menu is_dropdown_caret>
      <:toggle>Menu</:toggle>
      <:item>Item 1</:item>
      <:item>Item 2</:item>
      <:item>Item 3</:item>
    </.select_menu>
  </.subnav_search_context>
  <.subnav_search>
    <.text_input type="search" />
  </.subnav_search>
</.subnav>

attributes
Attributes

class (:string) - Additional classname. Defaults to nil.
is_wrap (:boolean) - Allows child elements to wrap, for example a link row followed by a search field. Defaults to false. Global attributes are accepted.

slots
Slots

inner_block (required) - Subnav components.

reference
Reference

status
Status

Feature complete.

subnav_links(assigns)

Subnav link row. See subnav/1.

attributes
Attributes

aria_label (:string) - Adds attribute aria-label to the subnav links element. Defaults to nil.
class (:string) - Additional classname. Defaults to nil.
classes (:map) - Additional classnames for subnav links elements.
Any provided value will be appended to the default classname.
Default map:
```
%{
  subnav_links: "", # Outer container (nav element)
  item: "",         # Link item element
}
```
Defaults to %{item: nil, subnav_links: nil}.

Global attributes are accepted.

slots
Slots

item (required) - Subnav buttons item. To create a link element, pass attribute href, navigate or patch. Accepts attributes:
- is_selected (:boolean) - Shows the selected state.
- href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other slot attributes to the link.
- patch (:string) - Link attribute - see href.
- navigate (:string) - Link attribute - see href.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.

subnav_search(assigns)

Subnav search field. See subnav/1.

attributes
Attributes

class (:string) - Additional classname. Defaults to nil. Global attributes are accepted.

slots
Slots

inner_block (required) - Contents.

subnav_search_context(assigns)

Subnav search filter adjacent to the search field. See subnav/1.

attributes
Attributes

class (:string) - Additional classname. Defaults to nil. Global attributes are accepted.

slots
Slots

inner_block (required) - Contents.

tabnav(assigns)

Generates a tab navigation.

Tabs are by default rendered as buttons. To create link elements, pass attribute href, navigate or patch.

<.tabnav aria_label="Topics navigation">
  <:item href="#url" is_selected>
    Link tab
  </:item>
  <:item>
    Button tab
  </:item>
</.tabnav>

examples
Examples

When a link attribute is supplied to the item slot, links are created with Phoenix.Component.link/1, passing all other slot attributes to the link. Link examples:

<:item href="#url">href link</:item>
<:item navigate={Routes.page_path(@socket, :index)}>navigate link</:item>
<:item patch={Routes.page_path(@socket, :index)}>patch link</:item>

Add other types of content, such as icons and counters:

<.tabnav>
  <:item href="#url" is_selected>
    <.octicon name="comment-discussion-16" />
    <span>Conversation</span>
    <.counter>2</.counter>
  </:item>
  <:item href="#url">
    <.octicon name="check-circle-16" />
    <span>Done</span>
    <.counter>99</.counter>
  </:item>
</.tabnav>

Position additional content to the far end of the tabs.

A button placed at the far end:

<.tabnav>
  <:item href="#url" is_selected>
    One
  </:item>
  <:item href="#url">
    Two
  </:item>
  <:position_end>
    <a class="btn btn-sm" href="#url" role="button">Button</a>
  </:position_end>
</.tabnav>

Extra content (not a button) is styled using attribute is_extra:

<.tabnav>
  <:item href="#url" is_selected>
    One
  </:item>
  <:item href="#url">
    Two
  </:item>
  <:position_end is_extra>
    Tabnav widget text here.
  </:position_end>
</.tabnav>

Create small tabs (similar to tabs inside a select_menu/1) with is_small:

<.tabnav>
  <:item is_small is_selected>
    One
  </:item>
  <:item is_small>
    Two
  </:item>
</.tabnav>

attributes
Attributes

class (:string) - Additional classname. Defaults to nil.

classes (:map) - Additional classnames for tabnav elements.

Any provided value will be appended to the default classname.

Default map:

%{
  tabnav: "",       # Outer container
  nav: "",          # Nav element
  tab: "",          # Tab link element
  position_end: "", # Container for elements positions at the far end
}

Defaults to %{nav: nil, position_end: nil, tab: nil, tabnav: nil}.

aria_label (:string) - Adds attribute aria-label to the outer element. Defaults to nil. Global attributes are accepted.

slots
Slots

item (required) - Tab item content. Tabs are by default rendered as buttons. To create a link element, pass attribute href, navigate or patch. Accepts attributes:
- is_selected (:boolean) - Shows the selected state.
- is_small (:boolean) - Creates a small tab, similar to tabs inside a select_menu/1.
- href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other slot attributes to the link.
- patch (:string) - Link attribute - see href.
- navigate (:string) - Link attribute - see href.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.
position_end - Container for elements positions at the far end. Accepts attributes:
- is_extra (:boolean) - Adds styles to optimise additional bits of text and links.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the far end container.

reference
Reference

status
Status

Feature complete.

underline_nav(assigns)

Generates a tab navigation with minimal underlined selected state, typically used for navigation placed at the top of the page.

Tabs are by default rendered as buttons. To create link elements, pass attribute href, navigate or patch.

<.underline_nav aria_label="Site navigation">
  <:item href="#url" is_selected>
    Link tab
  </:item>
  <:item>
    Button tab
  </:item>
</.underline_nav>

examples
Examples

When a link attribute is supplied to the item slot, links are created with Phoenix.Component.link/1, passing all other slot attributes to the link. Link examples:

<:item href="#url">href link</:item>
<:item navigate={Routes.page_path(@socket, :index)}>navigate link</:item>
<:item patch={Routes.page_path(@socket, :index)}>patch link</:item>

Add other types of content, such as icons and counters:

<.underline_nav>
  <:item href="#url" is_selected>
    <.octicon name="comment-discussion-16" />
    <span>Conversation</span>
    <.counter>2</.counter>
  </:item>
  <:item href="#url">
    <.octicon name="check-circle-16" />
    <span>Done</span>
    <.counter>99</.counter>
  </:item>
</.underline_nav>

Position additional content to the far end of the tabs.

A button placed at the far end:

<.underline_nav>
  <:item href="#url" is_selected>
    One
  </:item>
  <:item href="#url">
    Two
  </:item>
  <:position_end>
    <a class="btn btn-sm" href="#url" role="button">Button</a>
  </:position_end>
</.underline_nav>

Use is_container_width in combination with container styles to make navigation fill the width of the container:

<.underline_nav is_container_width classes={%{
    container: "container-sm"
  }}>
  <:item href="#url" is_selected>
    One
  </:item>
  <:item href="#url">
    Two
  </:item>
  <:position_end>
    <a class="btn btn-sm" href="#url" role="button">Button</a>
  </:position_end>
</.underline_nav>

attributes
Attributes

class (:string) - Additional classname. Defaults to nil.

classes (:map) - Additional classnames for underline nav elements.

Any provided value will be appended to the default classname.

Default map:

%{
  underline_nav: "", # Outer container (nav element)
  container: "",     # Extra container wrapper when using attr is_container_width
  body: "",          # Tabs wrapper
  tab: "",           # Tab link element
  position_end: "",  # Container for elements positions at the far end
}

Defaults to %{body: nil, container: nil, position_end: nil, tab: nil, underline_nav: nil}.

is_container_width (:boolean) - Use in combination with container styles to make navigation fill the width of the container.
For example:
```
<.underline_nav is_container_width classes={%{
  container: "container-sm"
}}>
  ...
</.underline_nav>
```
Defaults to false.
is_reversed (:boolean) - In left-to-right views the navigation will be positioned at the right. Defaults to false.
aria_label (:string) - Adds attribute aria-label to the outer element. Defaults to nil. Global attributes are accepted.

slots
Slots

item (required) - Tab item content: either a link or a button.Tab item content. Tabs are by default rendered as buttons. To create a link element, pass attribute href, navigate or patch.Accepts attributes:
- is_selected (:boolean) - Shows the selected state.
- href (:any) - Link attribute. The link is created with Phoenix.Component.link/1, passing all other slot attributes to the link.
- patch (:string) - Link attribute - see href.
- navigate (:string) - Link attribute - see href.
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the item element.
position_end - Container for elements positions at the far end. Accepts attributes:
- class (:string) - Additional classname.
- style (:string) - Additional CSS styles.
- rest (:any) - Additional HTML attributes added to the far end container.

reference
Reference