Lustre.Ui.Accordion

An accordion is made up of one or more collapsible sections with content. Each accordion item is made up of a header and a trigger button, and the panel that contains the collapsible content.

Lustre.Ui.Accordion.view []
    [ Lustre.Ui.Accordion.item
        "..."
        []
        (Lustre.Ui.Accordion.heading []
            [ Lustre.Ui.Accordion.trigger []
                [ Html.span [] [ Html.text "..." ] ]
            ]
        )
        (Lustre.Ui.Accordion.panel []
            [ Html.p [] [ Html.text "..." ]
            , Lustre.Ui.Accordion.close []
                [ Html.text "..." ]
            ]
        )
    ]

accordion.view is the container for all accordion items. It manages keyboard interaction and open state for each item.
Each accordion.item represents a single collapsible section within the accordion. It must have a unique name within the accordion to identify it.
An accordion.heading contains the trigger button for the item as its only child.
The accordion.trigger is the button that toggles the open state of an accordion item. It must not contain any other interactive elements.
The accordion.panel contains the collapsible content for the item.
The optional accordion.close trigger can be placed within the panel content to provide an additional way to close the accordion item.

Accessibility

The accordion component follows the WAI-ARIA Authoring Practices for the accordion pattern. This means appropriate roles, ARIA attributes, and keyboard interactions are handled for you, including:

role "region" on the accordion root, with managed aria-orientation for horizontal or vertical accordions.
role "heading" on each accordion item heading, with a default aria-level of 3.
role "button" on each accordion item trigger, with managed aria-expanded, and aria-controls attributes.
role "region" on each accordion item panel, with managed aria-labelledby attribute.
Keyboard interactions for navigation between accordion item triggers using Arrow Up/Down, Arrow Left/Right, Home, and End keys.
Retention of focus when accordion items are closed.

Usage notes

Avoid accordions with only one item, as they do not provide any functionality not already provided by the native <details> HTML element.

Recipes

You can use these recipes as starting points to build common types of accordions. Copy and paste them into your apps and adapt them as needed!

Basic use

The basic scaffold for any accordion. In this default configuration, the state of the accordion is uncontrolled and managed internally. Only one item can open at a time and keyboard navigation does not loop when reaching the first or last item.

Lustre.Ui.Accordion.view []
    [ Lustre.Ui.Accordion.item "..."
        []
        (Lustre.Ui.Accordion.heading []
            [ Lustre.Ui.Accordion.trigger [] [ Html.span [] [ Html.text "..." ] ] ]
        )
        (Lustre.Ui.Accordion.panel []
            [ Html.p [] [ Html.text "..." ]
            , Lustre.Ui.Accordion.close [] [ Html.text "..." ]
            ]
        )
    , Lustre.Ui.Accordion.item "..."
        []
        (Lustre.Ui.Accordion.heading []
            [ Lustre.Ui.Accordion.trigger [] [ Html.span [] [ Html.text "..." ] ] ]
        )
        (Lustre.Ui.Accordion.panel []
            [ Html.p [] [ Html.text "..." ]
            , Lustre.Ui.Accordion.close [] [ Html.text "..." ]
            ]
        )
    ]

This configuration allows multiple accordion items to be open at once, and keyboard navigation will loop back to the first item after the last, and vice versa.

Lustre.Ui.Accordion.view
    [ Lustre.Ui.Accordion.multiple, Lustre.Ui.Accordion.loop True ]
    [ Lustre.Ui.Accordion.item "..."
        []
        (Lustre.Ui.Accordion.heading []
            [ Lustre.Ui.Accordion.trigger [] [ Html.span [] [ Html.text "..." ] ] ]
        )
        (Lustre.Ui.Accordion.panel []
            [ Html.p [] [ Html.text "..." ]
            , Lustre.Ui.Accordion.close [] [ Html.text "..." ]
            ]
        )
    , Lustre.Ui.Accordion.item "..."
        []
        (Lustre.Ui.Accordion.heading []
            [ Lustre.Ui.Accordion.trigger [] [ Html.span [] [ Html.text "..." ] ] ]
        )
        (Lustre.Ui.Accordion.panel []
            [ Html.p [] [ Html.text "..." ]
            , Lustre.Ui.Accordion.close [] [ Html.text "..." ]
            ]
        )
    ]

Force item open

By explicitly setting the open attribute on an accordion item, it becomes controlled and will always be open unless the the open attribute is changed. This lets you pin certain items open or closed regardless of user interaction.

Lustre.Ui.Accordion.view
    [ Lustre.Ui.Accordion.open True ]
    [ Lustre.Ui.Accordion.item "..."
        [ Lustre.Ui.Accordion.open True ]
        (Lustre.Ui.Accordion.heading []
            [ Lustre.Ui.Accordion.trigger [] [ Html.text "..." ] ]
        )
        (Lustre.Ui.Accordion.panel [] [ todo ])
    , Lustre.Ui.Accordion.item "..."
        []
        (Lustre.Ui.Accordion.heading []
            [ Lustre.Ui.Accordion.trigger [] [ Html.text "..." ] ]
        )
        (Lustre.Ui.Accordion.panel [] [ Html.text "..." ])
    ]

Types

type AccordionItem a

type AccordionPanel a

type AccordionTrigger a

Elements

view : List (Attribute a) -> List (AccordionItem a) -> Html a

The root accordion element is a container for multiple accordion items.

Tag

<lustre-accordion>

Attributes

default_value, horizontal, label, loop, multiple, single, value, vertical.

Events

on_value_change

Styling

This element has a default display of block.

Accessibility notes

The accordion supports keyboard navigation between accordion item triggers using the following keys in addition to the standard tabbing behaviour:

Home moves focus to the first accordion item trigger.
End moves focus to the last accordion item trigger.
When in a vertical accordion...
- Arrow Up moves focus to the previous accordion item trigger.
- Arrow Down moves focus to the next accordion item trigger.
When in a horizontal accordion...
- Arrow Left moves focus to the previous accordion item trigger.
- Arrow Right moves focus to the next accordion item trigger.

Authors may provide an accessible label for the accordion to help assistive technologies identify it, but this is not required.

Managed attributes

The following attributes must not be set manually on the accordion, as these are managed by the component and are necessary for accessibility:

role

item :

String

-> List (Attribute a)

-> Html a

-> AccordionPanel a

-> AccordionItem a

Each accordion item represents a single collapsible section within the accordion. It must have a unique name within the accordion to identify it.

Tag

<lustre-accordion-item>

Attributes

default_open, open.

Events

on_hide, on_open_change, on_show.

Styling

This element has a default display of block.

The following CSS custom states can be used to style this element:

:state(open) is applied when the accordion item is expanded.

heading : List (Attribute a) -> AccordionTrigger a -> Html a

An accordion heading heading contains the trigger button for an accordion item as its only child.

Tag

<lustre-accordion-heading>

Attributes

level.

Styling

This element has a default display of block.

The following CSS custom states can be used to style this element:

:state(open) is applied when the containing accordion item is expanded.

Managed attributes

The following attributes must not be set manually on the heading, as these are managed by the component and are necessary for accessibility:

role

trigger : List (Attribute a) -> List (Html a) -> AccordionTrigger a

The accordion trigger is the button that toggles the open state of an accordion item. It must not contain any other interactive elements.

Tag

<lustre-accordion-trigger>

Attributes

label.

Styling

The following CSS custom states can be used to style this element:

:state(open) is applied when the containing accordion item is expanded.

Managed attributes

The following attributes must not be set manually on the accordion, as these are managed by the component and are necessary for accessibility:

aria-controls
aria-expanded
role

panel : List (Attribute a) -> List (Html a) -> AccordionPanel a

The accordion panel contains the collapsible content for the containing accordion item.

Tag

<lustre-accordion-panel>

Styling

This element has a default display of block.

The following CSS custom states can be used to style this element:

:state(open) is applied when the containing accordion item is expanded.

The following CSS custom properties can be used to style this element or its children:

--accordion-panel-width
--accordion-panel-height

Accessibility notes

When the panel is collapsed, any content within is made inert. This prevents focus from moving into the hidden content and ensures screen readers and other assistive technologies do not announce it. Because of this, it's important to make sure that the accordion panel is made visually hidden when collapsed so that sighted users do not try to interact with the panel's content.

Managed attributes

The following attributes must not be set manually on the accordion, as these are managed by the component and are necessary for accessibility:

aria-labelledby

close : List (Attribute a) -> List (Html a) -> Html a

The optional accordion close trigger can be placed within the panel content to provide an additional way to collapse the containing accordion item without navigating back to the item header.

Tag

<lustre-accordion-trigger>

Attributes

label.

Styling

This element has a default display of inline.

The following CSS custom states can be used to style this element:

:state(open) is applied when the containing accordion item is expanded.

Managed attributes

The following attributes must not be set manually on the accordion, as these are managed by the component and are necessary for accessibility:

aria-controls
aria-expanded
role

Attributes

label : String -> Attribute a

Provides an accessible label to an accordion or an item trigger. When used on an accordion, it is announced by assistive technologies to help identify the accordion.

It should be used on an accordion item trigger if the trigger's content does not contain that can be used to automatically generate an accessible label.

In both cases, the label is used for assistive technolgies only and is not visible to sighted users.

loop : Bool -> Attribute a

Controls whether keyboard navigation in an accordion loops from the last item back to the first and vice versa.

open : Bool -> Attribute a

Set the open state of an individual accordion item, making it controlled by your application and overriding any state managed by the containing accordion.

Where possible, it is preferable to manage the open state of accordion items centrally using the value attribute on the containing accordion, but this attribute can be useful when you need to pin certain items open or closed regardless of user interaction.

Note: in a controlled component, the state is managed by your application and must be updated in response to user interaction by handling the on_open_change event.
To set whether an accordion item is initially open when first rendered, consider using the default_open attribute instead.

default_open : Bool -> Attribute a

Set whether an individual accordion item is open by default when first rendered in an uncontrolled accordion. This value is only taken into account if the containing accordion does not have its own default_value attribute.

value : List String -> Attribute a

Set the current open items for a controlled accordion.

Note: in a controlled component, the state is managed by your application and must be updated in response to user interaction by handling the on_value_change or on_open_change events.
To let the component manage its own state, use the default_value attribute to set the initial open items instead.

default_value : List String -> Attribute a

Set the default open items for an uncontrolled accordion. This is a list of item names that should be open when the accordion first renders.

Note: an uncontrolled component is responsible for managing its own state and subsequent changes to the default_value will not be reflected in the component after the initial render.
To control the accordion's state from your application, use the value attribute instead.

single : Attribute a

Constrain an accordion to only allow a single item to be open at a time.

multiple : Attribute a

Allow multiple accordion items to be open at the same time.

horizontal : Attribute a

Set an accordion's orientation to horizontal. This changes keyboard navigation to use Arrow Left and Right keys instead of Up and Down.

vertical : Attribute a

Set an accordion's orientation to vertical. This is the default behaviour for an accordion and uses Arrow Up and Down keys for keyboard navigation.

level : Int -> Attribute a

Set the heading level for an accordion item's heading. This sets the aria-level attribute on the heading element to help assistive technologies understand the structure of the page. The value is clamped between 1 and 9.

Events

on_value_change : (List String -> a) -> Attribute a

An event emitted by an accordion when the open state of any of its items changes. The handler is passed a list of the names of all currently open items.

In a controlled accordion, this event should be used to update your application state with the new open items. Your application may ignore this event to prevent the open state of the accordion from changing.

In an uncontrolled accordion, this event can be used to respond to changes in the accordion's open state, for example by loading content dynamically when an item is opened.

on_open_change : (( String, Bool ) -> a) -> Attribute a

An event emitted by an individual accordion item when its open state changes. The handler is passed the name of the item and its new open state.

Note: like other DOM events, this event bubbles and can be listened for on the containing accordion.

on_show : (String -> a) -> Attribute a

An event emitted by an individual accordion item when it is expanded.

Note: like other DOM events, this event bubbles and can be listened for on the containing accordion.

on_hide : (String -> a) -> Attribute a

An event emitted by an individual accordion item when it is collapsed.

Note: like other DOM events, this event bubbles and can be listened for on the containing accordion.

hayleigh-dot-dev/elm-lustre-ui/1.0.0

Lustre.Ui.Accordion

Accessibility

Usage notes

Recipes

Basic use

Multiple open items, looping navigation

Force item open

Types

Elements

Tag

Attributes

Events

Styling

Accessibility notes

Managed attributes

Tag

Attributes

Events

Styling

Tag

Attributes

Styling

Managed attributes

Tag

Attributes

Styling

Managed attributes

Tag

Styling

Accessibility notes

Managed attributes

Tag

Attributes

Styling

Managed attributes

Attributes

Events

Modules