PrimerLive.Component (PrimerLive v0.3.2)
PrimerLive components.
Link to this section Summary
Alerts
Generates an alert message.
Wrapper to render a vertical stack of alert/1
messages with spacing in between.
Avatars
User profile image.
Generates a badge-like icon or logo.
Generates a larger "parent" avatar with a smaller "child" overlaid on top.
Blankslate
Generates fallback content if the actual content does not yet exist or if the user needs to perform an action.
Box
Generates a content container.
Branch name
Formats a branch name.
Dialog
Dialog, often called Modal.
Drawer
Generates a drawer with configuration options for backdrop, position and behavior.
Drawer content. See drawer/1
.
Styled HTML
Adds styling to HTML.
Forms
Generates a checkbox.
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.
Generates a validation message for a form input.
Generates a radio button.
Groups radio buttons in a tab-like row.
Generates a single or multiple select input.
Generates a text input field.
Generates a textarea.
Header
Generates a navigational header, to be placed at the top of the page.
Labels
Adds a count to navigational elements and buttons.
Issue labels are used for adding labels to issues and pull requests. They also come with emoji support.
Generates a label element.
Shows an item's status.
Layout
Generates a responsive-friendly page layout with 2 columns.
Links
Generates a consistent link-like appearance of actual links and spans inside links.
Pagination
Generates a control to navigate search results.
Progress
Generates a progress bar to visualize task completion.
Subhead
Configurable and styled h2 heading.
Theme
Creates a wrapper that sets the light/dark color mode and theme, with support for color blindness.
Generates theme menu options as an action_list/1
, to be used inside an action_menu/1
.
Timeline
Generates a timeline item to display items on a vertical timeline.
Truncate
Shortens text with ellipsis.
Link to this section Alerts
alert(assigns)
Generates an alert message.
<.alert>
Flash message goes here.
</.alert>
examples
Examples
Add color to the alert by using attribute state
. Possible states:
- "default" - light blue
- "info" - same as default
- "success" - light green
- "warning" - light yellow
- "error" - pink
Add a success color to the alert:
<.alert state="success">
You're done!
</.alert>
Multiline message:
<.alert state="success">
<p>You're done!</p>
<p>You may close this message</p>
</.alert>
To add an extra bottom margin to a stack of alerts, wrap the alerts in alert_messages/1
.
attributes
Attributes
class
(:string
) - Additional classname.classes
(:map
) - Additional classnames for the alert element and alert states.Any provided value will be appended to the default classname.
Default map:
%{ alert: "", # Outer container state_default: "", # Alert color modifier state_info: "", # Alert color modifier state_success: "", # Alert color modifier state_warning: "", # Alert color modifier state_error: "", # Alert color modifier }
Defaults to
%{alert: nil, state_default: nil, state_error: nil, state_info: nil, state_success: nil, state_warning: nil}
.state
(:string
) - Color mapping:- "default" - light blue
- "info" - same as default
- "success" - light green
- "warning" - light yellow
- "error" - pink
Must be one of
"default"
,"info"
,"success"
,"warning"
, or"error"
.
is_full
(:boolean
) - Renders the alert full width, with border and border radius removed. Defaults tofalse
. Global attributes are accepted.
slots
Slots
inner_block
(required) - Alert content.
reference
Reference
status
Status
To do:
- Flash (page) banner
alert_messages(assigns)
Wrapper to render a vertical stack of alert/1
messages with spacing in between.
<.alert_messages>
<.alert is_success>
Message 1
</.alert>
<.alert class="mt-4">
Message 2
</.alert>
</.alert_messages>
Rest of content
attributes
Attributes
class
(:string
) - Additional classname. Global attributes are accepted.
slots
Slots
inner_block
(required) - Alert messages content.
reference
Reference
status
Status
Feature complete.
Link to this section Avatars
avatar(assigns)
User profile image.
A simple wrapper function that returns an img
element, styled square and rounded. For correct rendering, the input image must be square.
<.avatar src="user.jpg" />
examples
Examples
Set the size (possible values: 1 - 8):
<.avatar size="1" src="user.jpg" />
Or set the size using regular img
tags:
<.avatar src="user.jpg" width="20" height="20" />
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
.src
(:string
) - Image source attribute. Defaults tonil
.width
(:string
) - Image width attribute. Defaults tonil
.height
(:string
) - Image height attribute. Defaults tonil
.alt
(:string
) - Image alt attribute. Defaults tonil
.size
(:any
) - Avatar size (number or number as string).Values translate to sizes:
- 1:
16px
- 2:
20px
- 3:
24px
(default) - 4:
28px
- 5:
32px
- 6:
40px
- 7:
48px
- 8:
64px
Defaults to
3
.- 1:
Global attributes are accepted.
reference
Reference
status
Status
Feature complete.
circle_badge(assigns)
Generates a badge-like icon or logo.
<.circle_badge>
<:octicon name="alert-16" />
</.circle_badge>
examples
Examples
Use slot octicon
to create an octicon/1
icon
<.circle_badge>
<:octicon name="alert-16" />
</.circle_badge>
Use slot img
to create an image icon
<.circle_badge>
<:img src="https://github.com/travis-ci.png" />
</.circle_badge>
Create a large badge (size "medium" or "large"):
<.circle_badge size="medium">
<:octicon name="alert-24" />
</.circle_badge>
Badges are by default rendered as div elements. To create link elements, pass attribute href
, navigate
or patch
. Link examples:
<.circle_badge href="#url">...</.circle_badge>
<.circle_badge navigate={Routes.page_path(@socket, :index)}>...</.circle_badge>
<.circle_badge patch={Routes.page_path(@socket, :index, :details)}>...</.circle_badge>
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
.size
(:string
) - Badge size: "small", "medium" or "large".Sizes:
- small:
56px
(default) - medium:
96px
- large:
128px
Defaults to
"small"
.- small:
href
(:any
) - Link attribute. If used, the badge will be created withPhoenix.Component.link/1
, passing all other attributes to the link.patch
(:string
) - Link attribute - seehref
.navigate
(:string
) - Link attribute - seehref
. Global attributes are accepted.
slots
Slots
octicon
- Generates a badge icon withocticon/1
. Accepts attributes:name
(:string
) - Octicon name.class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - Attributes supplied to theocticon
component.
img
- Generates a badge icon with animg
tag. Accepts attributes:src
(:any
) - Image source attribute.class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - HTML attributes supplied to theimg
element.
reference
Reference
status
Status
Feature complete.
parent_child_avatar(assigns)
Generates a larger "parent" avatar with a smaller "child" overlaid on top.
examples
Examples
Use slots parent
and child
to create the avatars using avatar/1
attributes:
<.parent_child_avatar>
<:parent src="emma.jpg" size="7" />
<:child src="kim.jpg" size="2" />
</.parent_child_avatar>
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
. Global attributes are accepted.
slots
Slots
parent
- Generates a parent avatar. Accepts attributes:child
- Generates a child avatar. Accepts attributes:
reference
Reference
status
Status
Feature complete.
Link to this section Blankslate
blankslate(assigns)
Generates fallback content if the actual content does not yet exist or if the user needs to perform an action.
<.blankslate>
<:heading>
This is a blank slate
</:heading>
<p>Use it to provide information when no dynamic content exists.</p>
</.blankslate>
Blankslate is created with slots that are applied in this order:
octicon
orimg
heading
inner_block
action
(multiple)
examples
Examples
With an octicon/1
:
<.blankslate>
<:octicon name="rocket-24" />
...
</.blankslate>
With an image:
<.blankslate>
<:img src="https://ghicons.github.com/assets/images/blue/png/Pull%20request.png" alt="" />
...
</.blankslate>
With an action:
<.blankslate>
<:action>
<.button is_primary>New project</.button>
</:action>
...
</.blankslate>
Narrow layout:
<.blankslate is_narrow>
...
</.blankslate>
Large text:
<.blankslate is_large>
...
</.blankslate>
Combined slots, in a box/1
:
<.box>
<.blankslate>
<:heading>
This is a blank slate
</:heading>
<:img
src="https://ghicons.github.com/assets/images/blue/png/Pull%20request.png"
alt=""
/>
<:action>
<.button is_primary>New project</.button>
</:action>
<:action>
<.button is_link>Learn more</.button>
</:action>
<p>Use it to provide information when no dynamic content exists.</p>
</.blankslate>
</.box>
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
.classes
(:map
) - Additional classnames for blankslate elements.Any provided value will be appended to the default classname.
Default map:
%{ blankslate: "", # Blankslate wrapper octicon: "" # Icon element img: "", # Image element heading: "", # Heading element action: "", # Action element }
Defaults to
%{action: nil, blankslate: nil, heading: nil, img: nil, octicon: nil}
.is_narrow
(:boolean
) - Narrows the blankslate container to not occupy the entire available width. Defaults tofalse
.is_large
(:boolean
) - Increases the size of the text in the blankslate. Defaults tofalse
.is_spacious
(:boolean
) - Significantly increases the vertical padding. Defaults tofalse
. Global attributes are accepted.
slots
Slots
heading
- Heading. Accepts attributes:tag
(:string
) - HTML tag used for the heading.Default: "h3".
class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - Attributes supplied to the heading.
octicon
- Adds a top icon withocticon/1
. Accepts attributes:name
(:string
) - Octicon name.class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - Attributes supplied to theocticon
component.
img
- Adds a top image with animg
tag. Accepts attributes:src
(:string
) - Image source attribute.alt
(:string
) - Image alt attribute.width
(:string
) - Image width attribute.height
(:string
) - Image height attribute.class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - HTML attributes supplied to theimg
element.
action
- Adds a wrapper for a button or link. Accepts attributes:class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - HTML attributes supplied to the action wrapper element.
inner_block
- Regular content.
reference
Reference
status
Status
Feature complete.
Link to this section Box
box(assigns)
Generates a content container.
A box
is a container with rounded corners, a white background, and a light gray border.
By default, there are no other styles, such as padding; however, these can be introduced
with utility classes as needed.
<.box>
Content
</.box>
Slots allow for the creation of alternative styles and layouts.
<.box>
<:header>Header</:header>
<:body>Body</:body>
<:row>Row</:row>
<:footer>Footer</:footer>
</.box>
examples
Examples
Row themes:
<.box>
<:row is_gray>Row</:row>
<:row is_hover_gray>Row</:row>
<:row is_yellow>Row</:row>
<:row is_hover_blue>Row</:row>
<:row is_blue>Row</:row>
</.box>
Box theme - "danger box":
<.box is_danger>
<:row>Row</:row>
<:row>Row</:row>
</.box>
Header theme - blue header:
<.box>
<:header is_blue>Blue header</:header>
</.box>
Render a row for each search result:
<.box>
<:row :for={result <- @results}>
<%= result %>
</:row>
</.box>
Conditionally show an alert:
<.box>
<.alert :if={@show_alert}>Alert message</.alert>
<:body>
Body
</:body>
</.box>
Header title. Slot header
can be omitted:
<.box>
<:header_title>
Title
</:header_title>
Content
</.box>
Header with a button, using both header
and header_title
slots. The title will be inserted as first header element:
<.box>
<:header class="d-flex flex-items-center">
<.button is_primary is_smmall>
Button
</.button>
</:header>
<:header_title class="flex-auto">
Title
</:header_title>
<:body>
Rest
</:body>
</.box>
Header with icon button:
<.box>
<:header class="d-flex flex-justify-between flex-items-start">
<.button is_close_button aria-label="Close" class="flex-shrink-0 pl-4">
<.octicon name="x-16" />
</.button>
</:header>
<:header_title>
A very long title that wraps onto multiple lines without overlapping
or wrapping underneath the icon to it's right
</:header_title>
<:body>Content</:body>
</.box>
Links can be placed inside rows. Use :let
to get access to the classes.link
class. With Phoenix.Component.link/1
:
<.box>
<:row :let={classes}>
<.link href="/" class={classes.link}>Home</.link>
</:row>
</.box>
To make the entire row a link, pass attribute href
, navigate
or patch
. Tweak the link behaviour with row attrs is_hover_gray
, is_hover_blue
and/or Primer CSS modifier class "no-underline". Link examples:
<:row href="#url">href link</:row>
<:row navigate={Routes.page_path(@socket, :index)}>navigate link</:row>
<:row patch={Routes.page_path(@socket, :index)}>patch link</:row>
<:row href="#url" class="no-underline" is_hover_gray>Link, no underline, hover gray</:row>
Box can be used inside dialogs. To make the box content scrollable within the confined space of the dialog, use is_scrollable
. This will make all inner content (inner_block
, body
and rows
) scrollable between header and footer.
To limit the height of the box, either:
- Use class "Box--scrollable" to limit the height to
324px
- Add style "max-height"
<.box is_scrollable class="Box--scrollable">
<:header>Fixed header</:header>
<:body>Scrollable body</:body>
<:row>Scrollable row</:row>
<:row>Scrollable row</:row>
...
<:footer>Fixed footer</:footer>
</.box>
<.box is_scrollable style="max-height: 80vh">
<:header>Fixed header</:header>
<:body>Scrollable body</:body>
<:row>Scrollable row</:row>
<:row>Scrollable row</:row>
...
<:footer>Fixed footer</:footer>
</.box>
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:
%{ box: "", # Box element header: "", # Box header row element row: "", # Box content row element body: "", # Content element footer: "", # Footer row element header_title: "", # Title element within a header row link: "", # Class for links }
Defaults to
%{body: nil, box: nil, footer: nil, header: nil, header_title: nil, link: nil, row: nil}
.is_blue
(:boolean
) - Generates a blue box theme. Defaults tofalse
.is_danger
(:boolean
) - Generates a danger color box theme. Only works with slotsrow
andbody
. Use class "color-border-danger" for a lighter danger color. Defaults tofalse
.is_border_dashed
(:boolean
) - Applies a dashed border to the box. Defaults tofalse
.is_condensed
(:boolean
) - Condenses line-height and reduces the padding on the Y axis. Defaults tofalse
.is_spacious
(:boolean
) - Increases padding and increases the title font size. Defaults tofalse
.is_scrollable
(:boolean
) - Makes inner content (consistent ofinner_block
,body
androws
) scrollable in a box with maximum height. Defaults tofalse
. Global attributes are accepted.
slots
Slots
header
- Generates a header row element. Accepts attributes:class
(:string
) - Additional classname.is_blue
(:boolean
) - Change the header border and background to blue.
header_title
- Generates a title within the header. If no header slot is passed, the header title will be wrapped inside a header element. Accepts attributes:class
(:string
) - Additional classname.
row
- Generates a content row element. To create a link element, pass attributehref
,navigate
orpatch
. Accepts attributes:is_blue
(:boolean
) - Blue row theme.is_gray
(:boolean
) - Gray row theme.is_yellow
(:boolean
) - Yellow row theme.is_hover_blue
(:boolean
) - Changes to blue row theme on hover.is_hover_gray
(:boolean
) - Changes to gray row theme on hover.is_focus_blue
(:boolean
) - Changes to blue row theme on focus.is_focus_gray
(:boolean
) - Changes to gray row theme on focus.is_navigation_focus
(:boolean
) - Combine with a theme color to highlight the row when using keyboard commands.is_unread
(:boolean
) - Apply a blue vertical line highlight for indicating a row contains unread items.href
(:any
) - Link attribute. The link is created withPhoenix.Component.link/1
, passing all other slot attributes to the link.patch
(:string
) - Link attribute - seehref
.navigate
(:string
) - Link attribute - seehref
.class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - Additional HTML attributes added to the row element.
body
- Generates a body element. Accepts attributes:class
(:string
) - Additional classname.
footer
- Generates a footer row element. Accepts attributes:class
(:string
) - Additional classname.
inner_block
(required) - Unstructured content.
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.
<.box classes={%{ link: "link-x" }}>
<:row :let={classes}>
<.link href="/" class={["my-link", classes.link]}>Home</.link>
</:row>
</.box>
Results in:
<div class="Box">
<div class="Box-row">
<a href="/" class="my-link Box-row-link link-x">Home</a>
</div>
</div>
reference
Reference
status
Status
Feature complete.
Link to this section Branch name
branch_name(assigns)
Formats a branch name.
<.branch_name>development</.branch_name>
examples
Examples
A branch name may be a link. Links are created with Phoenix.Component.link/1
, passing all other attributes to the link. Link examples:
<.branch_name href="#url">some-name</.branch_name>
<.branch_name navigate={Routes.page_path(@socket, :index)}>some-name</.branch_name>
<.branch_name patch={Routes.page_path(@socket, :index, :details)}>some-name</.branch_name>
Add an icon before the branch name:
<.branch_name>
<.octicon name="git-branch-16" />
some-name
</.branch_name>
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
.href
(:any
) - Link attribute. The link is created withPhoenix.Component.link/1
, passing all other attributes to the link.patch
(:string
) - Link attribute - seehref
.navigate
(:string
) - Link attribute - seehref
. Global attributes are accepted.
slots
Slots
inner_block
(required) - The branch name text and optionally an icon.
reference
Reference
status
Status
Feature complete.
Link to this section Dialog
dialog(assigns)
Dialog, often called Modal.
A dialog is created with box/1
slots.
<.dialog>
<:header_title>Title</:header_title>
<:body>
Message in a dialog
</:body>
</.dialog>
Showing and hiding is done with JS function Prompt
from dialogic-js, included in PrimerLive.
Function Prompt.show
requires a selector. When placed inside the dialog component, the selector can be replaced with this
:
<.dialog id="my-dialog">
<:body>
Message in a dialog
<.button onclick="Prompt.hide(this)">Close</.button>
</:body>
</.dialog>
<.button onclick="Prompt.show('#my-dialog')">Open dialog</.button>
examples
Examples
Add a backdrop. Optionally add is_light_backdrop
or is_dark_backdrop
:
<.dialog is_backdrop is_dark_backdrop>
...
</.dialog>
Create a modal dialog; clicking the backdrop (if used) or outside of the dialog will not close the dialog:
<.dialog is_modal>
...
</.dialog>
Close the dialog with the Escape key:
<.dialog is_escapable>
...
</.dialog>
Create faster fade in and out:
<.dialog is_fast>
...
</.dialog>
A narrow dialog:
<.dialog is_narrow>
...
</.dialog>
A wide dialog:
<.dialog is_wide>
...
</.dialog>
Focus the first element after opening the dialog. Pass a selector to match the element.
<.dialog focus_first="#login_first_name">
...
</.dialog>
or
<.dialog focus_first="[name=login\[first_name\]]">
...
</.dialog>
Long content will automatically show a scrollbar. To change the maxium height of the dialog, use a CSS value. Use unit vh
or %
.
<.dialog max_height="50vh">
...
</.dialog>
Add a header title and a footer.
box
slot header
slot is automatically added when header_title
is used.
<.dialog>
<:header_title>Title</:header_title>
...
<:footer>Footer</:footer>
</.dialog>
A dialog with rows:
<.dialog>
<:header_title>Title</:header_title>
<:row>Row 1</:row>
<:row>Row 2</:row>
<:row>Row 3</:row>
<:row>Row 4</:row>
<:footer>Footer</:footer>
</.dialog>
Dialog are wrapped inside a Phoenix.Compoennt.focus_wrap/1
so that navigating with Tab won't leave the dialog.
<.dialog is_backdrop is_modal>
<:header_title>Title</:header_title>
<:body>
<.text_input form={:user} field={:first_name} is_group />
<.text_input form={:user} field={:last_name} is_group />
</:body>
</.dialog>
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
.classes
(:map
) - Additional classnames for dialog elements.Any provided value will be appended to the default classname.
Default map:
%{ # Dialog classes dialog_wrapper: "", # The outer element dialog: "", # Dialog element # Box classes - see box component: box: "", header: "", row: "", body: "", footer: "", header_title: "", link: "", }
Defaults to
%{body: nil, box: nil, dialog: nil, dialog_wrapper: nil, footer: nil, header: nil, header_title: nil, link: nil, row: nil}
.is_backdrop
(:boolean
) - Generates a medium backdrop background color. Defaults tofalse
.is_dark_backdrop
(:boolean
) - Generates a darker backdrop background color. Defaults tofalse
.is_medium_backdrop
(:boolean
) - Generates a medium backdrop background color (default). Defaults tofalse
.is_light_backdrop
(:boolean
) - Generates a lighter backdrop background color. Defaults tofalse
.is_fast
(:boolean
) - Generates fast fade transitions for backdrop and content. Defaults tofalse
.is_modal
(:boolean
) - Generates a modal dialog; clicking the backdrop (if used) or outside of the dialog will not close the dialog. Defaults tofalse
.is_escapable
(:boolean
) - Closes the content when pressing the Escape key. Defaults tofalse
.focus_first
(:string
) - Focus the first element after opening the dialog. Pass a selector to match the element.is_narrow
(:boolean
) - Generates a smaller dialog, width:320px
(default:440px
). Defaults tofalse
.is_wide
(:boolean
) - Generates a wider dialog, width:640px
(default:440px
). Defaults tofalse
.max_height
(:string
) - Maximum height of the dialog as CSS value. Use unitvh
or%
. Defaults to"80vh"
.max_width
(:string
) - Maximum width of the dialog as CSS value. Use unitvh
or%
. Defaults to"90vw"
. Global attributes are accepted.
slots
Slots
header_title
- Dialog header title. Usesbox/1
header_title
slot.Note that slotheader
is automatically created to ensure the correct close button.Accepts attributes:class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - Additional attributes.
body
- Dialog body. Usesbox/1
body
slot. Accepts attributes:class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - Additional attributes.
row
- Dialog row. Usesbox/1
row
slot. Accepts attributes:class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - Additional attributes.
footer
- Dialog footer. Usesbox/1
footer
slot. Accepts attributes:class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - Additional attributes.
inner_block
- Unstructured dialog content. Usesbox/1
inner_block
slot.
reference
Reference
status
Status
Feature complete.
Link to this section Drawer
drawer(assigns)
Generates a drawer with configuration options for backdrop, position and behavior.
<.drawer>
<.drawer_content>
Content
</.drawer_content>
</.drawer>
Showing and hiding is done with JS function Prompt
from dialogic-js, included in PrimerLive.
Function Prompt.show
requires a selector. When placed inside the drawer component, the selector can be replaced with this
:
<.drawer id="my-drawer">
<.drawer_content>
<.button onclick="Prompt.hide(this)">Close</.button>
Content
</.drawer_content>
</.drawer>
<.button onclick="Prompt.show('#my-drawer')">Open drawer</.button>
examples
Examples
By default the drawer width is defined by its content. To set an explicit width of the drawer content:
<.drawer>
<.drawer_content width="300px">
...
</.drawer_content>
</.drawer>
Add a backdrop. Optionally add is_light_backdrop
or is_dark_backdrop
:
<.drawer is_backdrop is_dark_backdrop>
...
</.drawer>
Create a modal drawer; clicking the backdrop (if used) or outside of the drawer will not close the drawer:
<.drawer is_modal>
...
</.drawer>
Close the drawer with the Escape key:
<.drawer is_escapable>
...
</.drawer>
Create faster slide in and out:
<.drawer is_fast>
...
</.drawer>
Focus the first element after opening the drawer. Pass a selector to match the element.
<.drawer focus_first="#login_first_name">
...
</.drawer>
or
<.drawer focus_first="[name=login\[first_name\]]">
...
</.drawer>
Create a local drawer (inside a container) with is_local
:
<div style="position: relative; overflow-x: hidden;">
Page content
<.drawer is_local>
<.drawer_content>
Content
</.drawer_content>
</.drawer>
</div>
Create a push drawer - where the drawer content pushes the adjacent content aside when it opens - with attr is_push
and the content to be pushed inside <.drawer>
:
<div style="position: relative; overflow-x: hidden;">
<.drawer is_push>
Page content
<.drawer_content>
Content
</.drawer_content>
</.drawer>
</div>
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
.is_far_side
(:boolean
) - Opens the drawer at the far end of the reading direction. Defaults tofalse
.is_backdrop
(:boolean
) - Generates a medium backdrop background color. Defaults tofalse
.is_dark_backdrop
(:boolean
) - Generates a darker backdrop background color. Defaults tofalse
.is_medium_backdrop
(:boolean
) - Generates a medium backdrop background color (default). Defaults tofalse
.is_light_backdrop
(:boolean
) - Generates a lighter backdrop background color. Defaults tofalse
.is_fast
(:boolean
) - Generates fast fade transitions for backdrop and content. Defaults tofalse
.is_modal
(:boolean
) - Generates a modal drawer; clicking the backdrop (if used) or outside of the drawer will not close the drawer. Defaults tofalse
.is_escapable
(:boolean
) - Closes the content when pressing the Escape key. Defaults tofalse
.is_local
(:boolean
) - Adds styles for a drawer inside a a container. Defaults tofalse
.is_push
(:boolean
) - Adds styles for a push drawer inside a a container. Defaults tofalse
.focus_first
(:string
) - Focus the first element after opening the drawer. Pass a selector to match the element. Global attributes are accepted.
slots
Slots
inner_block
- Drawer content and any adjacent elements. Usedrawer_content/1
for the content to be displayed inside the drawer.
reference
Reference
Neither Primer CSS nor Primer React provide a drawer component. However, a drawer is used on their documentation site (mobile view).
drawer_content(assigns)
Drawer content. See drawer/1
.
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
.width
(:string
) - Sets the width of the drawer as CSS value. Add unitpx
orrem
or other size unit.By default the drawer width is defined by its content.
Defaults to
nil
.
Global attributes are accepted.
slots
Slots
inner_block
- Drawer content.
Link to this section Styled HTML
styled_html(assigns)
Adds styling to HTML.
This can be used to format HTML generated by a Markdown library, or to create consistent layout of HTML content.
<.styled_html>
Content
</.styled_html>
attributes
Attributes
class
(:string
) - Additional classname. Global attributes are accepted.
slots
Slots
inner_block
(required) - Content to be formatted.
reference
Reference
status
Status
Feature complete.
Link to this section Forms
checkbox(assigns)
Generates a checkbox.
Wrapper around Phoenix.HTML.Form.checkbox/3
.
<.checkbox name="available_for_hire" />
examples
Examples
Set the checked state:
<.checkbox name="available_for_hire" checked />
Using the checkbox with form data. This will automatically create the checkbox label:
<.form let={f} for={@changeset} phx-change="validate" phx-submit="save">
<.checkbox form={f} field={:available_for_hire} />
</.form>
Pass a custom checkbox label with the label
slot:
<.checkbox form={:user} field={:available_for_hire}>
<:label>Some label</:label>
</.checkbox>
Add emphasis to the label:
<.checkbox name="available_for_hire" is_emphasised_label />
Add a hint below the label:
<.checkbox name="available_for_hire">
<:label>Some label</:label>
<:hint>
Add your <strong>resume</strong> below
</:hint>
</.checkbox>
Reveal extra details when the checkbox is checked:
<.checkbox name="available_for_hire">
<: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>
</.checkbox>
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 usingform
andfield
).checked
(:boolean
) - The state of the checkbox (when not usingform
andfield
).checked_value
(:string
) - The value to be sent when the checkbox is checked. Ifchecked_value
equalsvalue
, the checkbox is marked checked. Defaults to "true". Defaults tonil
.hidden_input
(:string
) - Controls if the component will generate a hidden input to submit the unchecked checkbox value or not. Defaults to "true". UsesPhoenix.HTML.Form.hidden_input/3
. Defaults to"true"
.value
(:string
) - Checkbox value attribute (when not usingform
andfield
).is_multiple
(:boolean
) - When creating a list of checkboxes. Appends[]
to the input name so that a list of values is passed to the form events. Defaults tofalse
.is_emphasised_label
(:boolean
) - Adds emphasis to the label. Defaults tofalse
.is_omit_label
(:boolean
) - Omits any label. Defaults tofalse
.class
(:string
) - Additional classname. Defaults tonil
.classes
(:map
) - Additional classnames for checkbox elements.Any provided value will be appended to the default classname.
Default map:
%{ container: "", # Checkbox container label_container: "", # Input label container label: "", # Input label input: "", # Checkbox input element hint: "", # Hint message container disclosure: "" # Disclosure container (inline) }
Defaults to
%{container: nil, disclosure: nil, hint: nil, input: nil, label: nil, label_container: nil}
.
Global attributes are accepted.
slots
Slots
label
- Custom checkbox label. Overides the derived label when using aform
andfield
. 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 checkbox 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 checkbox 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.
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 usingfield
. Defaults tonil
.is_hide_label
(:boolean
) - Omits the label when usingfield
. Defaults tofalse
.class
(:string
) - Additional classname. Defaults tonil
.for
(:string
) - Internally used bytext_input/1
andtextarea/1
when usingis_form_group
orform_group
. Label attribute to associate the label with the input.for
should be the same as the input'sid
. Defaults tonil
.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 tonil
.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). Seetext_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 usingform
andfield
).value
(:string
) - Input value. Defaults tonil
.checked
(:boolean
) - The state of the radio button (when not usingform
andfield
).is_emphasised_label
(:boolean
) - Adds emphasis to the label. Defaults tofalse
.is_omit_label
(:boolean
) - Omits any label. Defaults tofalse
.class
(:string
) - Additional classname. Defaults tonil
.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 aform
andfield
. 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 tonil
.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
) - Attributeid
prefix to create unique ids. Defaults tonil
. Global attributes are accepted.
slots
Slots
radio_button
- Generates a radio button. Accepts attributes:value
(:string
) - Seeradio_button/1
.name
(:string
) - Seeradio_button/1
.checked
(:boolean
) - Seeradio_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 usingform
andfield
).options
(:any
) (required) - Selectable options (list, map or keyword list).selected
(:any
) - Selected option or options (string for single select, list when usingis_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. SeePhoenix.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. UsesPhoenix.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 tofalse
.is_large
(:boolean
) - Creates a large select. Defaults tofalse
.is_short
(:boolean
) - Creates a short select. Defaults tofalse
.is_shorter
(:boolean
) - Creates a shorter select. Defaults tofalse
.is_full_width
(:boolean
) - Full width select. Defaults tofalse
.is_auto_height
(:boolean
) - When usingis_multiple
: sets the size to the number of options. Defaults tofalse
.is_monospace
(:boolean
) - Uses a monospace font. Defaults tofalse
.is_form_group
(:boolean
) - Inserts the select inside aform_group/1
. Attributesform
andfield
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 aform_group/1
with given attributes, alongsideform
andfield
to generate a group label.validation_message
(:any
) - Function to write a custom validation message (in case of error or success). Seetext_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 tonil
.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 usingform
andfield
).value
(:string
) - Text input value attribute (when not usingform
andfield
).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 tofalse
.is_full_width
(:boolean
) - Full width input. Defaults tofalse
.is_hide_webkit_autofill
(:boolean
) - Hide WebKit's contact info autofill icon. Defaults tofalse
.is_large
(:boolean
) - Additional padding creates a higher input box. If no width is specified, the input box is slightly wider. Defaults tofalse
.is_small
(:boolean
) - Smaller (less high) input with smaller text size. Defaults tofalse
.is_short
(:boolean
) - Inside a form group. Generates an input with a reduced width. Defaults tofalse
.is_shorter
(:boolean
) - Inside a form group. Generates an input with a even more reduced width. Defaults tofalse
.is_monospace
(:boolean
) - Uses a monospace font. Defaults tofalse
.is_form_group
(:boolean
) - Inserts the input inside aform_group/1
. Attributesform
andfield
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 aform_group/1
with given attributes, alongsideform
andfield
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 achangeset
- 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
- If form is a
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 aocticon/1
component is used.trailing_action
- Container for a trailing action. Commonly aocticon/1
component, or abutton/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
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 tofalse
.is_secondary
(:boolean
) - Secondary color. Defaults tofalse
. 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 tofalse
. 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 tofalse
.is_secondary
(:boolean
) - Generates a label with a subtler text color. Defaults tofalse
.is_accent
(:boolean
) - Accent color. Defaults tofalse
.is_success
(:boolean
) - Success color. Defaults tofalse
.is_attention
(:boolean
) - Attention color. Defaults tofalse
.is_severe
(:boolean
) - Severe color. Defaults tofalse
.is_danger
(:boolean
) - Danger color. Defaults tofalse
.is_open
(:boolean
) - Open color. Defaults tofalse
.is_closed
(:boolean
) - Closed color. Defaults tofalse
.is_done
(:boolean
) - Done color. Defaults tofalse
.is_sponsors
(:boolean
) - Sponsors color. Defaults tofalse
.is_large
(:boolean
) - Larger label. Defaults tofalse
.is_inline
(:boolean
) - For use in running text. Adapts line height and font size to text. Defaults tofalse
. 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 tofalse
.is_open
(:boolean
) - Open state color. Defaults tofalse
.is_merged
(:boolean
) - Merged state color. Defaults tofalse
.is_closed
(:boolean
) - Closed state color. Defaults tofalse
.is_small
(:boolean
) - Smaller state label. Defaults tofalse
. 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 sidebaris_divided
withis_flow_row_hidden
hides the divideris_divided
withis_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
) - Useis_divided
in conjunction with thelayout_item/1
element with attributedivider
to show a divider between the main content and the sidebar. Generates a 1px line between main and sidebar. Defaults tofalse
.is_narrow_sidebar
(:boolean
) - Smaller sidebar size. Widths: md: 240px, lg: 256px. Defaults tofalse
.is_wide_sidebar
(:boolean
) - Wider sidebar size. Widths: md: 296px, lg: 320px, xl: 344px. Defaults tofalse
.is_gutter_none
(:boolean
) - Changes the gutter size to 0px. Defaults tofalse
.is_gutter_condensed
(:boolean
) - Changes the gutter size to 16px. Defaults tofalse
.is_gutter_spacious
(:boolean
) - Changes the gutter sizes to: md: 16px, lg: 32px, xl: 40px. Defaults tofalse
.is_sidebar_position_start
(:boolean
) - Places the sidebar at the start (commonly at the left) (default). Defaults tofalse
.is_sidebar_position_end
(:boolean
) - Places the sidebar at the end (commonly at the right) on desktop. Defaults tofalse
.is_sidebar_position_flow_row_start
(:boolean
) - When stacked, render the sidebar first (default). Defaults tofalse
.is_sidebar_position_flow_row_end
(:boolean
) - When stacked, render the sidebar last. Defaults tofalse
.is_sidebar_position_flow_row_none
(:boolean
) - When stacked, hide the sidebar. Defaults tofalse
.is_flow_row_until_md
(:boolean
) - Stacks when container is md. Defaults tofalse
.is_flow_row_until_lg
(:boolean
) - Stacks when container is lg. Defaults tofalse
.is_centered_lg
(:boolean
) - Generates a wrapper aroundmain
to keep its content centered up to max width "lg". Defaults tofalse
.is_centered_md
(:boolean
) - Generates a wrapper aroundmain
to keep its content centered up to max width "md". Defaults tofalse
.is_centered_xl
(:boolean
) - Generates a wrapper aroundmain
to keep its content centered up to max width "xl". Defaults tofalse
.is_flow_row_hidden
(:boolean
) - On a small screen (up to 544px). Hides the horizontal divider. Defaults tofalse
.is_flow_row_shallow
(:boolean
) - On a small screen (up to 544px). Generates a filled 8px horizontal divider. Defaults tofalse
. Global attributes are accepted.
slots
Slots
main
- Generates a main element. Default gutter sizes: md: 16px, lg: 24px (change withis_gutter_none
,is_gutter_condensed
andis_gutter_spacious
). Stacks when container issm
(change withis_flow_row_until_md
andis_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 of1
,2
,"1"
, or"2"
.
divider
- Generates a divider element. The divider will only be shown with optionis_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 withis_narrow_sidebar
andis_wide_sidebar
). Accepts attributes:order
(:any
) - Seemain
slot. Default value: 1.Must be one of1
,2
,"1"
, or"2"
.
reference
Reference
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 tonil
.is_primary
(:boolean
) - Turns the link color to blue only on hover. Defaults tofalse
.is_secondary
(:boolean
) - Turns the link color to blue only on hover, using a darker color. Defaults tofalse
.is_muted
(:boolean
) - Turns the link to muted gray, also on hover. Defaults tofalse
.is_no_underline
(:boolean
) - Removes the underline on hover. Defaults tofalse
.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 tofalse
.href
(:any
) - Link attribute. The link is created withPhoenix.Component.link/1
, passing all other attributes to the link.patch
(:string
) - Link attribute - seehref
.navigate
(:string
) - Link attribute - seehref
. Global attributes are accepted.
slots
Slots
inner_block
(required) - Link content.
reference
Reference
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 tonil
. Global attributes are accepted.
reference
Reference
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 tonil
.size
(:any
) - Spinner size (number or number as string). Defaults to18
.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 Pagination
pagination(assigns)
Generates a control to navigate search results.
<.pagination
page_count={@page_count}
current_page={@current_page}
link_path={fn page_num -> "/page/#{page_num}" end}
/>
features
Features
- Configure the page number ranges for siblings and sides
- Optionally disable page number display (minimal UI)
- Custom labels
- Custom classnames for all elements
If pages in the center (controlled by sibling_count
) collide with pages near the sides (controlled by side_count
), the center section will be pushed away from the side.
examples
Examples
Simplified paginations, showing Next / Previous buttons:
<.pagination
...
is_numbered="false"
/>
Configure the number of sibling and boundary page numbers to show:
<.pagination
...
sibling_count="1" # default: 2
side_count="2" # default 1
/>
Provide custom labels:
<.pagination
...
labels={
%{
next_page: "Nächste Seite",
previous_page: "Vorherige Seite"
}
}
/>
attributes
Attributes
page_count
(:integer
) (required) - Result page count.current_page
(:integer
) (required) - Current page number.link_path
(:any
) (required) - Function that returns a path for the given page number. The link builder usesPhoenix.Component.link/1
with attributenavigate
. Extra options can be passed withlink_options
.Function signature:
(page_number) -> path
side_count
(:integer
) - Number of page links at both ends. Defaults to1
.sibling_count
(:integer
) - Number of page links at each side of the current page number element. Defaults to2
.is_numbered
(:any
) - Boolean atom or string. Showing page numbers. Defaults totrue
.class
(:string
) - Additional classname.classes
(:map
) - Additional classnames for pagination elements. Any provided value will be appended to the default classname.Default map:
%{ gap: "", pagination_container: "", pagination: "", previous_page: "", next_page: "", page: "" }
Defaults to
%{gap: nil, next_page: nil, page: nil, pagination: nil, pagination_container: nil, previous_page: nil}
.labels
(:map
) - Textual labels. Any provided value will override the default text. Defaults to%{aria_label_container: "Navigation", aria_label_next_page: "Next page", aria_label_page: "Page {page_number}", aria_label_previous_page: "Previous page", gap: "…", next_page: "Next", previous_page: "Previous"}
.link_options
(:map
) - Link options. Defaults to%{replace: false}
. Global attributes are accepted.
reference
Reference
status
Status
Feature complete.
Link to this section Progress
progress(assigns)
Generates a progress bar to visualize task completion.
The item slot creates the colored bar. Its width is a percentage value (0 - 100).
<.progress aria_label="Tasks: 8 of 10 complete">
<:item width="50"></:item>
</.progress>
examples
Examples
The default bar state is "success" (green). Possible states:
- "info" - blue
- "success" - green
- "warning" - ocher
- "error" - red
<.progress>
<:item width="50" state="error"></:item>
</.progress>
Use multiple items to show a multicolored bar:
<.progress>
<:item width="50" state="success"></:item>
<:item width="30" state="warning"></:item>
<:item width="10" state="error"></:item>
<:item width="5" state="info"></:item>
</.progress>
Create a large progress bar:
<.progress is_large>
<:item width="50"></:item>
</.progress>
Create a small progress bar:
<.progress is_small>
<:item width="50"></:item>
</.progress>
Create an inline progress bar:
<span class="text-small color-fg-muted mr-2">4 of 16</span>
<.progress is_inline style="width: 160px;">
<:item width="25"></:item>
</.progress>
attributes
Attributes
aria_label
(:string
) - Adds attributearia-label
to the outer element. Defaults tonil
.class
(:string
) - Additional classname. Defaults tonil
.classes
(:map
) - Additional classnames for progress elements.Any provided value will be appended to the default classname.
Default map:
%{ progress: "", # Outer container item: "", # Colored bar element state_success: "", # Color bar modifier state_info: "", # Color bar modifier state_warning: "", # Color bar modifier state_error: "", # Color bar modifier }
Defaults to
%{item: nil, progress: nil, state_error: nil, state_info: nil, state_success: nil, state_warning: nil}
.is_large
(:boolean
) - Creates a large progress bar. Defaults tofalse
.is_small
(:boolean
) - Creates a small progress bar. Defaults tofalse
.is_inline
(:boolean
) - Creates an inline progress bar, to be used next to other elements.The "progress" element must have a width, for example:
<.progress is_inline style="width: 160px;"> <:item width="25"></:item> </.progress>
Defaults to
false
.
Global attributes are accepted.
slots
Slots
item
(required) - Colored bar. Accepts attributes:width
(:any
) - String or integer. Percentage value (0 - 100).state
(:string
) - Color mapping:- "info" - blue
- "success" - green
- "warning" - ocher
- "error" - red
Must be one of "info"
, "success"
, "warning"
, or "error"
.
reference
Reference
status
Status
Feature complete.
Link to this section Subhead
subhead(assigns)
Configurable and styled h2 heading.
</.subhead>Plain subhead</.subhead>
examples
Examples
Add a top margin when separating sections on a settings page:
</.subhead is_spacious>Subhead</.subhead>
Create a danger zone heading:
</.subhead is_danger>Plain subhead</.subhead>
Add a description:
<.subhead>
Heading
<:description>
Description
</:description>
</.subhead>
Add an action (button or link):
<.subhead>
Heading
<:actions>
<.button is_primary>Action</.button>
</:actions>
</.subhead>
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
.classes
(:map
) - Additional classnames for subhead elements.Any provided value will be appended to the default classname.
Default map:
%{ subhead: "", # Subhead container heading: "", # h2 heading description: "", # Description element actions: "", # Actions section element }
Defaults to
%{actions: nil, description: nil, heading: nil, subhead: nil}
.is_spacious
(:boolean
) - Add a top margin. Defaults tofalse
.is_danger
(:boolean
) - Makes the text bold and red. This is useful for warning users. Defaults tofalse
. Global attributes are accepted.
slots
Slots
inner_block
(required) - Heading content.description
- Description content.actions
- Actions content.
reference
Reference
status
Status
Feature complete.
Link to this section Theme
theme(assigns)
Creates a wrapper that sets the light/dark color mode and theme, with support for color blindness.
See also PrimerLive.Theme
.
alternative-method
Alternative method
Instead of using a wrapper, consider using Theme.html_attributes
to set a theme on a component or element directly:
<.button
{PrimerLive.Theme.html_attributes([color_mode: "dark", dark_theme: "dark_high_contrast"])}
>Button</.button>
<.octicon name="sun-24"
{PrimerLive.Theme.html_attributes(%{color_mode: "dark", dark_theme: "dark_dimmed"})}
/>
theme-wrapper-examples
Theme wrapper examples
Use default settings:
<.theme>
Content
</.theme>
Set the color mode to dark and specify the dark theme:
<.theme color_mode="dark" dark_theme="dark_dimmed">
Content
</.theme>
Specify light and dark themes:
<.theme color_mode="dark" light_theme="light_high_contrast" dark_theme="dark_high_contrast">
Content
</.theme>
Use a theme_state
struct for easier passing around state:
assigns = assign
|> assign(:theme_state, %{
color_mode: "light",
light_theme: "light_high_contrast",
dark_theme: "dark_high_contrast"
})
<.theme theme_state={@theme_state}>
Content
</.theme>
attributes
Attributes
theme_state
(:map
) - Sets all theme values at once. Defaults tonil
.color_mode
(:string
) - Color mode. Defaults to"auto"
.light_theme
(:string
) - Light theme.Possible values:
- "light"
- "light_high_contrast"
- "light_colorblind"
- "light_tritanopia"
Defaults to
"light"
.dark_theme
(:string
) - Dark theme.Possible values:
- "dark"
- "dark_dimmed"
- "dark_high_contrast"
- "dark_colorblind"
- "dark_tritanopia"
Defaults to
"dark"
.is_inline
(:boolean
) - Renders the wrapper as aspan
. Useful for setting the color on an inline element. Defaults tofalse
. Global attributes are accepted.
slots
Slots
inner_block
(required) - Content.
reference
Reference
status
Status
Feature complete.
Link to this section Timeline
timeline_item(assigns)
Generates a timeline item to display items on a vertical timeline.
<.timeline_item>
<:badge>
<.octicon name="flame-16" />
</:badge>
Everything is fine
</.timeline_item>
examples
Examples
Add color to the badge by using attribute state
. Possible states:
- "default" - light gray
- "info" - blue
- "success" - green
- "warning" - ocher
- "error" - red
<.timeline_item state="error">
<:badge>
<.octicon name="flame-16" />
</:badge>
Everything will be fine
</.timeline_item>
Alternatively, use Primer CSS modifier classes on the badge slot to assign colors:
<.timeline_item>
<:badge class="color-bg-done-emphasis color-fg-on-emphasis">
<.octicon name="flame-16" />
</:badge>
Everything will be fine
</.timeline_item>
When a link attribute is supplied to the badge slot, links are created with Phoenix.Component.link/1
, passing all other slot attributes to the link. Link examples:
<:badge href="#url">href link</:item>
<:badge navigate={Routes.page_path(@socket, :index)}>navigate link</:item>
<:badge patch={Routes.page_path(@socket, :index)}>patch link</:item>
Create a condensed item, reducing the vertical padding and removing the background from the badge item:
<.timeline_item is_condensed>
<:badge>
<.octicon name="git-commit-16" />
</:badge>
My commit
</.timeline_item>
Display an avatar of the author:
<.timeline_item>
<:badge>
<.octicon name="git-commit-16" />
</:badge>
<:avatar>
<.avatar size="6" src="user.jpg" />
</:avatar>
Someone's commit
</.timeline_item>
Create a visual break in the timeline with attribute is_break
. This adds a horizontal bar across the timeline to show that something has disrupted it.
<.timeline_item state="error">
<:badge><.octicon name="flame-16" /></:badge>
Everything will be fine
</.timeline_item>
<.timeline_item is_break />
<.timeline_item state="success">
<:badge><.octicon name="smiley-16" /></:badge>
Everything is fine
</.timeline_item>
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
.classes
(:map
) - Additional classnames for timeline elements.Any provided value will be appended to the default classname.
Default map:
%{ timeline_item: "", # Outer container badge: "", # Badge element avatar: "", # Avatar container body: "", # Body element state_default: "", # Badge color modifier state_info: "", # Badge color modifier state_success: "", # Badge color modifier state_warning: "", # Badge color modifier state_error: "", # Badge color modifier }
Defaults to
%{avatar: nil, badge: nil, body: nil, state_default: nil, state_error: nil, state_info: nil, state_success: nil, state_warning: nil, timeline_item: nil}
.state
(:string
) - Create a badge color variant by setting the state. Color mapping:- "default" - light gray
- "info" - blue
- "success" - green
- "warning" - ocher
- "error" - red
Must be one of
"default"
,"info"
,"success"
,"warning"
, or"error"
.
is_condensed
(:boolean
) - Creates a condensed item, reducing the vertical padding and removing the background from the badge item. Defaults tofalse
.is_break
(:boolean
) - Creates a visual break in the timeline. This adds a horizontal bar across the timeline to show that something has disrupted it. Ignores any slots. Defaults tofalse
. Global attributes are accepted.
slots
Slots
badge
- Badge content. Pass anocticon/1
to display an icon. To create a link element, pass attributehref
,navigate
orpatch
. Accepts attributes:href
(:any
) - Link attribute. The link is created withPhoenix.Component.link/1
, passing all other slot attributes to the link.patch
(:string
) - Link attribute - seehref
.navigate
(:string
) - Link attribute - seehref
.class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - Additional HTML attributes added to the badge element.
avatar
- Avatar container.inner_block
- Item body.
reference
Reference
status
Status
Feature complete.
Link to this section Truncate
truncate(assigns)
Shortens text with ellipsis.
<.truncate>
<:item>really-long-text</:item>
</.truncate>
examples
Examples
Change the default generated HTML tags (default "span"). Note that the outer element is by default styled as inline-flex
, regardless of the provided tag.
<.truncate tag="ol">
<:item tag="li">really-long-text</:item>
<:item tag="li">really-long-text</:item>
</.truncate>
Tabs are by default rendered as span
elements. To create link elements, pass attribute href
, navigate
or patch
. 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>
Multiple item texts will truncate evenly.
<.truncate>
<:item>really-long-text</:item>
<:item>really-long-text</:item>
</.truncate>
Delay the truncating of specific items:
<.truncate>
<:item>really-long-user-nametext</:item>
<:item is_primary>really-long-project-name</:item>
</.truncate>
Expand the items on hover
and focus
:
<.truncate>
<:item expandable>really-long-text</:item>
<:item expandable>really-long-text</:item>
</.truncate>
Limit the maximum width by adding max-width
style:
<.truncate>
<:item is_expandable style="max-width: 300px;">
really-long-text
</:item>
</.truncate>
attributes
Attributes
class
(:string
) - Additional classname. Defaults tonil
.classes
(:map
) - Additional classnames for truncate elements.Any provided value will be appended to the default classname.
Default map:
%{ truncate: "", # Truncate wrapper element item: "", # Text wrapper element }
Defaults to
%{item: nil, truncate: nil}
.tag
(:string
) - HTML tag used for the truncate wrapper. Defaults to"span"
. Global attributes are accepted.
slots
Slots
item
(required) - Wrapper around text to be truncated. Accepts attributes:tag
(:string
) - HTML tag used for the text wrapper.Default: "span".
href
(:any
) - Link attribute. The link is created withPhoenix.Component.link/1
, passing all other slot attributes to the link.patch
(:string
) - Link attribute - seehref
.navigate
(:string
) - Link attribute - seehref
.is_primary
(:boolean
) - When using multiple items. Delays the truncating of the item.is_expandable
(:boolean
) - When using multiple items. Will expand the text onhover
andfocus
.class
(:string
) - Additional classname.style
(:string
) - Additional CSS styles.rest
(:any
) - Attributes supplied to the item.
reference
Reference
status
Status
Feature complete.