Renders a set of headings that control the visibility of their content sections.

Configuration

Generate the component with default options:

build_accordion()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :accordion, base_class: "accordion", modifiers: []]

Usage

<.accordion id="dog-breeds">
  <:section title="Golden Retriever">
    <p>
      Friendly, intelligent, great with families. Origin: Scotland. Needs
      regular exercise.
    </p>
  </:section>
  <:section title="Siberian Husky">
    <p>
      Energetic, outgoing, distinctive appearance. Origin: Northeast Asia.
      Loves cold climates.
    </p>
  </:section>
  <:section title="Dachshund">
    <p>
      Playful, stubborn, small size. Origin: Germany. Enjoys sniffing games.
    </p>
  </:section>
</.accordion>

This component needs the Doggo.Accordion JavaScript hook for the arrow keys. See Phoenix LiveView Hooks for registering it.

Keyboard

• Enter or Space - toggle the section of the focused header.
• Up and Down - move to the previous or the next header, wrapping at the ends.
• Home and End - first and last header.

Every header is in the tab order, which is what the ARIA Authoring Practices describe for an accordion. The arrow keys, Home and End need the colocated hook; the ARIA Authoring Practices list them as optional for an accordion.

Renders a card in an article tag, typically used repetitively in a grid or flex box layout.

Configuration

Generate the component with default options:

build_card()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :card, base_class: "card", modifiers: []]

Usage

<.card>
  <:image>
    <img src="image.png" alt="Picture of a dog dressed in a poncho." />
  </:image>
  <:header><h2>Dog Fashion Show</h2></:header>
  <:body>
    The next dog fashion show is coming up quickly. Here's what you need
    to look out for.
  </:body>
  <:footer>
    <span>2023-11-15 12:24</span>
    <span>Events</span>
  </:footer>
</.card>

Formats a Date, DateTime, or NaiveDateTime as a date and renders it in a <time> element.

Configuration

Generate the component with default options:

build_date()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :date, base_class: nil, modifiers: []]

Usage

By default, the given value is formatted for display with to_string/1. This:

<.date value={~D[2023-02-05]} />

Will be rendered as:

<time datetime="2023-02-05">
  2023-02-05
</time>

You can also pass a custom formatter function. For example, if you are using ex_cldr_dates_times in your application, you could do this:

<.date
  value={~D[2023-02-05]}
  formatter={&MyApp.Cldr.Date.to_string!/1}
/>

Which, depending on your locale, may be rendered as:

<time datetime="2023-02-05">
  Feb 2, 2023
</time>

If you pass a title_formatter, a title attribute is added to the element. This can be useful if you want to render the value in a shortened or relative format, but still give the user access to the complete value. Note that the title attribute is only be accessible to users who use a pointer device. Some screen readers may however announce the datetime attribute that is always added.

<.date
  value={@date}
  formatter={&relative_date/1}
  title_formatter={&MyApp.Cldr.Date.to_string!/1}
/>

Finally, the component can shift a DateTime to a different time zone before converting it to a date:

<.date
  value={~U[2023-02-05 23:22:05Z]}
  timezone="Asia/Tokyo"
/>

Which would be rendered as:

<time datetime="2023-02-06">
  2023-02-06
</time>

Formats a DateTime or NaiveDateTime as a date time and renders it in a <time> element.

Configuration

Generate the component with default options:

build_datetime()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :datetime, base_class: nil, modifiers: []]

Usage

By default, the given value is formatted for display with to_string/1. This:

<.datetime value={~U[2023-02-05 12:22:06.003Z]} />

Will be rendered as:

<time datetime="2023-02-05T12:22:06.003Z">
  2023-02-05 12:22:06.003Z
</time>

You can also pass a custom formatter function. For example, if you are using ex_cldr_dates_times in your application, you could do this:

<.datetime
  value={~U[2023-02-05 14:22:06.003Z]}
  formatter={&MyApp.Cldr.DateTime.to_string!/1}
/>

Which, depending on your locale, may be rendered as:

<time datetime="2023-02-05T14:22:06.003Z">
  Feb 2, 2023, 14:22:06 PM
</time>

The component can also truncate the value before passing it to the formatter.

<.datetime
  value={~U[2023-02-05 12:22:06.003Z]}
  precision={:minute}
/>

If you pass a title_formatter, a title attribute is added to the element. This can be useful if you want to render the value in a shortened or relative format, but still give the user access to the complete value. Note that the title attribute is only be accessible to users who use a pointer device. Some screen readers may however announce the datetime attribute that is always added.

<.datetime
  value={@datetime}
  formatter={&relative_date/1}
  title_formatter={&MyApp.Cldr.DateTime.to_string!/1}
/>

Finally, the component can shift a DateTime to a different time zone:

<.datetime
  value={~U[2023-02-05 23:22:05Z]}
  timezone="Asia/Tokyo"
/>

Which would be rendered as:

<time datetime="2023-02-06T08:22:05+09:00">
  2023-02-06 08:22:05+09:00 JST Asia/Tokyo
</time>

The fallback component renders a given value unless it is empty, in which case it renders a fallback value instead.

The values nil, "", [] and %{} are treated as empty values.

This component optionally applies a formatter function to non-empty values.

The primary purpose of this component is to enhance accessibility. If a table cell or property list property has no value, an alternative text must be provided for screen readers.

Configuration

Generate the component with default options:

build_fallback()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :fallback, base_class: "fallback", modifiers: []]

Usage

Render the value of @some_value if it's available, or display the default placeholder otherwise:

<.fallback value={@some_value} />

Apply a formatter function to @some_value if it is not nil:

<.fallback value={@some_value} formatter={&format_date/1} />

Set a custom placeholder and text for screen readers:

<.fallback
  value={@some_value}
  placeholder="n/a"
  accessibility_text="not available"
/>

Renders a list of properties as key/value pairs.

This component is useful for displaying data in a structured format, such as a list of attributes for an entity. Each property is rendered as a <dt> element for the label and a <dd> element for the value.

Configuration

Generate the component with default options:

build_property_list()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :property_list, base_class: "property-list", modifiers: []]

Usage

Each property is specified using the :prop slot with a label attribute and an inner block.

<.property_list>
  <:prop label={gettext("Name")}>George</:prop>
  <:prop label={gettext("Age")}>42</:prop>
</.property_list>

Example CSS

For example CSS, you can have a look at the demo styles.

Renders a simple table.

Configuration

Generate the component with default options:

build_table()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :table, base_class: "table-container", modifiers: []]

Usage

<.table id="pets" rows={@pets}>
  <:col :let={p} label="name"><%= p.name %></:col>
  <:col :let={p} label="age"><%= p.age %></:col>
</.table>

Row actions

row_click sets phx-click on each cell, which reaches pointer users only. Where you use it, repeat the action as a link or button inside the row, so that it can also be reached by keyboard.

<.table id="pets" rows={@pets} row_click={&JS.navigate(~p"/pets/#{&1}")}>
  <:col :let={p} label="name">
    <.link navigate={~p"/pets/#{p}"}><%= p.name %></.link>
  </:col>
</.table>

Renders tab panels.

This component is meant for tabs that toggle content panels within the page. If you want to link to a different view or live action, use tab_navigation/1 instead.

Configuration

Generate the component with default options:

build_tabs()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :tabs, base_class: "tabs", modifiers: []]

Usage

<.tabs id="dog-breed-profiles" label="Dog Breed Profiles">
  <:panel label="Golden Retriever">
    <p>
      Friendly, intelligent, great with families. Origin: Scotland. Needs
      regular exercise.
    </p>
  </:panel>
  <:panel label="Siberian Husky">
    <p>
      Energetic, outgoing, distinctive appearance. Origin: Northeast Asia.
      Loves cold climates.
    </p>
  </:panel>
  <:panel label="Dachshund">
    <p>
      Playful, stubborn, small size. Origin: Germany. Enjoys sniffing games.
    </p>
  </:panel>
</.tabs>

This component needs the Doggo.Tabs JavaScript hook. See Phoenix LiveView Hooks for registering it.

Keyboard

• Left, Right, Up and Down - previous or next tab, wrapping at the ends. A tab list with orientation="horizontal" uses Left and Right, one with orientation="vertical" uses Up and Down.
• Home and End - first and last tab.
• Enter or Space - select the focused tab.

The tab list is a single tab stop.

Renders a tag, typically used for displaying labels, categories, or keywords.

Configuration

Generate the component with default options:

build_tag()

The build macro supports the common options name, base_class, and modifiers.

Default options

[
  name: :tag,
  base_class: "tag",
  modifiers: [
    size: [values: ["small", "normal", "medium", "large"], default: "normal"],
    variant: [
      values: [nil, "primary", "secondary", "info", "success", "warning",
       "danger"],
      default: nil
    ],
    shape: [values: [nil, "pill"], default: nil]
  ]
]

Usage

<.tag>Well-Trained</.tag>

With icon:

<.tag>
  Puppy
  <.icon><Heroicons.edit /></.icon>
</.tag>

With delete button:

<.tag>
  High Energy
  <.button
    phx-click="remove-tag"
    phx-value-tag="high-energy"
    aria-label="Remove tag"
  >
    <.icon><Heroicons.x /></.icon>
  </.button>
</.tag>

Example CSS

For example CSS, you can have a look at the demo styles.

Formats a Time, DateTime, or NaiveDateTime as a time and renders it in a <time> element.

Configuration

Generate the component with default options:

build_time()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :time, base_class: nil, modifiers: []]

Usage

By default, the given value is formatted for display with to_string/1. This:

<.time value={~T[12:22:06.003Z]} />

Will be rendered as:

<time datetime="12:22:06.003">
  12:22:06.003
</time>

You can also pass a custom formatter function. For example, if you are using ex_cldr_dates_times in your application, you could do this:

<.time
  value={~T[12:22:06.003]}
  formatter={&MyApp.Cldr.Time.to_string!/1}
/>

Which, depending on your locale, may be rendered as:

<time datetime="14:22:06.003">
  14:22:06 PM
</time>

The component can also truncate the value before passing it to the formatter.

<.time
  value={~U[2023-02-05 12:22:06.003Z]}
  precision={:minute}
/>

If you pass a title_formatter, a title attribute is added to the element. This can be useful if you want to render the value in a shortened or relative format, but still give the user access to the complete value. Note that the title attribute is only be accessible to users who use a pointer device. Some screen readers may however announce the datetime attribute that is always added.

<.time
  value={@time}
  formatter={&relative_time/1}
  title_formatter={&MyApp.Cldr.Time.to_string!/1}
/>

Finally, the component can shift a DateTime to a different time zone:

<.time
  value={~U[2023-02-05 23:22:05Z]}
  timezone="Asia/Tokyo"
/>

Which would be rendered as:

<time datetime="08:22:05">
  08:22:05
</time>

Renders a hierarchical list as a tree.

A good use case for this component is a folder structure. For navigation and other menus, a regular nested list should be preferred.

Configuration

Generate the component with default options:

build_tree()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :tree, base_class: "tree", modifiers: []]

Usage

<.tree label="Dogs">
  <tree_item>
    Breeds
    <:items>
      <.tree_item>Golden Retriever</.tree_item>
      <.tree_item>Labrador Retriever</.tree_item>
    </:items>
  </.tree_item>
  <.tree_item>
    Characteristics
    <:items>
      <.tree_item>Playful</.tree_item>
      <.tree_item>Loyal</.tree_item>
    </:items>
  </.tree_item>
</.tree>

CSS

You can target the wrapper with an attribute selector for the role:

[role="tree"] {}

This component needs the Doggo.Tree JavaScript hook. See Phoenix LiveView Hooks for registering it.

Keyboard

• Down and Up - move between the visible items. A collapsed branch takes its children out of the sequence.
• Right - expand the focused branch, or move to its first child if it is already expanded.
• Left - collapse the focused branch, or move to its parent if it is already collapsed or is a leaf.
• Home and End - first and last visible item.
• Printable characters - move to the next visible item whose label starts with what you type.

The tree is a single tab stop. Expanding and collapsing is the hook's own state, and it survives a LiveView patch. Selecting an item is not: the component renders aria-selected from the selected attribute of tree_item, so wire your own click or key handler and re-render.

Example CSS

For example CSS, you can have a look at the demo styles.

Renders a tree item within a tree/1.

This component can be used as a direct child of tree/1 or within the items slot of this component.

Configuration

Generate the component with default options:

build_tree_item()

The build macro supports the common options name, base_class, and modifiers.

Default options

[name: :tree_item, base_class: "tree-item", modifiers: []]

Usage

<.tree label="Dogs">
  <.tree_item>
    Breeds
    <:items>
      <.tree_item>Golden Retriever</.tree_item>
      <.tree_item>Labrador Retriever</.tree_item>
    </:items>
  </.tree_item>
  <.tree_item>
    Characteristics
    <:items>
      <.tree_item>Playful</.tree_item>
      <.tree_item>Loyal</.tree_item>
    </:items>
  </.tree_item>
</.tree>

Icons can be added before the label:

<.tree_item>
  <Heroicon.folder /> Breeds
  <:items>
    <.tree_item><Heroicon.document /> Golden Retriever</.tree_item>
    <.tree_item><Heroicon.document /> Labrador Retriever</.tree_item>
  </:items>
</.tree_item>

Example CSS

For example CSS, you can have a look at the demo styles.