tesk9 / accessible-html-with-css / Accessibility.Styled.Aria

Learn more about about W3C's Web Accessibility Initiative's Accessible Rich Internet Applications standards ("WAI-ARIA") at w3.org.

Please keep in mind that ARIA attributes are best used sparingly -- your users are better off with semantic HTML than they are with divs with many ARIA attributes. See No ARIA is better than BAD ARIA from the WAI-ARIA Authoring Practices guide.

activeDescendant : String -> Html.Styled.Attribute msg

Creates an aria-activedescendant attribute.

Identifies the currently-active element in order to provide an alternative way of managing focus.

Supported in container-y roles: application, composite, group, textbox, comboBox, grid, listBox, menu, menuBar, radioGroup, row, searchBox, select, spinButton, tabList, toolBar, tree, and treeGrid.

controls : List String -> Html.Styled.Attribute msg

Creates aria-controls attribute.

Pass a list of ids for the elements that are being controlled by the current element.

Supported by all elements.

owns : List String -> Html.Styled.Attribute msg

Creates aria-owns attribute.

Pass a list of ids for the elements that ought to be considered direct children of the current element. If possible, it's better to rely on the actual DOM structure, instead of using aria-owns.

A child should only have one parent. So an element's id should only be referenced by one aria-owns at a time.

Not supported by VoiceOver as of October 2022. Please see a11ysupport.io for more recent support testing.

Supported by all elements.

Providing More Info

label : String -> Html.Styled.Attribute msg

Creates an aria-label attribute.

Supported for all elements.

labelledBy : String -> Html.Styled.Attribute msg

Creates an aria-labelledby attribute.

Pass the unique string id of the labelling element. Only use this property if the label is visible (if the label is not visible, prefer Accessibility.Styled.Aria.label).

labeledBy : String -> Html.Styled.Attribute msg

Convenience alias for labelledBy.

details : String -> Html.Styled.Attribute msg

Supported by all elements.

Refer to a single extended description section--maybe a couple of paragraphs and a chart. Pass in the HTML id of an element with details about the current element to create an aria-details association.

The Editor's Draft for ARIA 1.3 allows multiple idrefs instead of just 1, but the current published ARIA spec only supports a singular idref.

describedBy : List String -> Html.Styled.Attribute msg

Supported by all elements. Pass it a list of ids of elements that describe the given element.

Pass in ids of elements that describe the current element to create an aria-describedby association.

You may wish to review the documentation for labelledBy and details as well -- which property you should use will depend on your specific UX requirements.

longDescription : String -> Html.Styled.Attribute msg

Creates the longDesc attribute with the given url, which should point to a text description of the content. This attribute is only supported on img tags.

import Accessibility exposing (Html, img)
import Accessibility.Aria exposing (longDescription)

view : Html msg
view =
    img
        "Growth Chart in Some Sweet Unit (Quarter 4)"
        [ longDescription "/quarter_4_summary#Growth" ]

Note that this is a deprecated HTML property, not an ARIA property. See MDN documentation on HTMLImageElement.longDesc for general documentation and Using longdesc (Technique H45) for accessibility documentation.

brailleLabel : String -> Html.Styled.Attribute msg

Add aria="braillelabel" to the attributes of an element.

Please note that this ARIA property is part of the Editor's Draft for ARIA 1.3 -- it's not an official part of a published spec yet.

keyShortcuts : List String -> Html.Styled.Attribute msg

Supported by all elements. Pass in a list of keyboard shortcuts to use the aria-keyshortcuts property.

keyShortcuts [ "Alt+Shift+P", "Control+F" ]

Note that this property only indicates to users that certain keyboard shortcuts exist -- this property does not change the behavior of the element to which it is attached. Please also note that it's nice to make the existence of keyboard shortcuts known to all users, not only to screenreader users!

Learn more about the purpose of from The WAI-ARIA Authoring Practices guide's Keyboard Shortcuts section.

Please be aware that providing single-character keyboard shortcuts may make using your site less accessible for some users. Read Understanding Success Criterion 2.1.4: Character Key Shortcuts to learn more.

roleDescription : String -> Html.Styled.Attribute msg

Supported by all elements.

Provide human-readable description of the role of an element. Should be used alongside an actual role--this is supplementary information.

Creates an aria-roledescription property.

Navigation and Flow

flowTo : List String -> Html.Styled.Attribute msg

Creates an aria-flowto attribute.

Provide an alternative document reading order and offer navigation to the elements referenced in the passed-in list of ids.

Supported by all elements.

Textbox Related

placeholder : String -> Html.Styled.Attribute msg

Supported by textbox and searchbox.

Provide a hint about an expected value.

Creates an aria-placeholder property.

Generally, you should use Html.Styled.Attributes.placeholder instead of using aria-placeholder. The only time that you should add an aria-placeholder attribute is if you're rolling your own widget that's required you to explicitly set a wai-aria role. See some guidance around "implicit" aria semantics here.

Table Related

colCount : Basics.Int -> Html.Styled.Attribute msg

Creates an aria-colcount attribute.

Describe the number of columns in a grid in which not all of the columns are currently in the DOM. (If all columns are already rendering, don't use this attribute.)

-1 indicates total column number is unknown.

Supported by elements with roles table, grid, and treegrid.

colIndex : Basics.Int -> Html.Styled.Attribute msg

Creates an aria-colindex attribute.

Indexing begins from 1, NOT 0. Plus, the colIndex should not be greater than the colCount! If a cell stretches across multiple columns, use the starting column index and colSpan.

The simplest rule is to put the colIndex on every child of a row.

Please note that if all of the columns of the table/grid are already present in the DOM, you do not need to use this property.

Supported by elements with roles cell, row, columnHeader, gridCell, and rowHeader.

colSpan : Basics.Int -> Html.Styled.Attribute msg

Creates an aria-colspan attribute.

Indicate how many columns-wide a cell is.

Please use the HTML attribute colspan instead of aria-colspan for native HTML tables.

Supported by elements with roles cell, columnHeader, gridCell, and rowHeader.

rowCount : Basics.Int -> Html.Styled.Attribute msg

Creates an aria-rowcount attribute.

Analagous to colcount.

rowIndex : Basics.Int -> Html.Styled.Attribute msg

Creates an aria-rowindex attribute.

Analagous to colIndex.

rowSpan : Basics.Int -> Html.Styled.Attribute msg

Creates an aria-rowspan attribute.

Analagous to colSpan.

Set Related

setSize : Basics.Int -> Html.Styled.Attribute msg

Creates an aria-setsize attribute.

setSize indicates the total number of items in a set where not all the items are currently present in the DOM.

Warning! The setSize is added to every set item, not to the element containing the set.

The ARIA docs include this example, which I've converted to Elm and shorted a bit:

import Accessibility.Styled exposing (..)
import Accessibility.Styled.Aria as Aria
import Accessibility.Styled.Role as Role
import Html.Styled.Attributes exposing (id)

view : List (Html msg)
view =
    [ h2 [ id "label_fruit" ] [ text "Available Fruit" ]
    , ul [ Role.listBox, Aria.labelledBy "label_fruit" ]
        [ li
            [ Role.option
            , Aria.setSize 16
            , Aria.posInSet 5
            ]
            [ text "apples" ]
        , li
            [ Role.option
            , Aria.setSize 16 -- <- Note the set size appears on the element, not on the container
            , Aria.posInSet 6
            ]
            [ text "bananas" ]
        ]
    ]

Supported by elements that might appear in a list: article, listItem, menuItem, option, radio, tab, menuitemcheckbox, menuitemradio, and treeItem.

posInSet : Basics.Int -> Html.Styled.Attribute msg

Creates an aria-posinset attribute.

Only necessary when not all of the items in the set are in the DOM. Use with setSize.

Supported by elements that might appear in a list: article, listItem, menuItem, option, radio, tab, menuitemcheckbox, menuitemradio, and treeItem.

Current

currentItem : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-current attribute, either aria-current=true or aria-current=false.

Only 1 element in a set should be marked as the current item.

Please double-check that you don't want Accessibility.Styled.Aria.selected instead.

Supported by all elements.

currentPage : Html.Styled.Attribute msg

Creates an aria-current attribute, as aria-current=page.

Indicate that a link in a nav or list is the current location.

Supported by all elements.

currentStep : Html.Styled.Attribute msg

Creates an aria-current attribute, as aria-current=step.

Indicate which step in a step-based flow is the current one.

Supported by all elements.

currentLocation : Html.Styled.Attribute msg

Supported by all elements.

currentDate : Html.Styled.Attribute msg

Creates an aria-current attribute, as aria-current=date.

As in a calendar.

Supported by all elements.

currentTime : Html.Styled.Attribute msg

Creates an aria-current attribute, as aria-current=time.

As in a timepicker.

Supported by all elements.

Inputs and Validation

required : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-required attribute.

Indicate whether user input is or is not required on a field for valid form submission.

Supported by comboBox, gridCell, listBox, radioGroup, spinButton, textBox, tree

invalid : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-invalid attribute.

Learn more about Using Aria-Invalid to Indicate an Error Field.

You may want to use Accessibility.Styled.Aria.errorMessage or Accessibility.Styled.Aria.describedBy to indicate what's invalid about the user's submission.

For invalid grammar or spelling specifically, use invalidGrammar and invalidSpelling respectively.

Supported for all elements.

invalidGrammar : Html.Styled.Attribute msg

Creates an aria-invalid="grammar" attribute.

Supported for all elements.

invalidSpelling : Html.Styled.Attribute msg

Creates an aria-invalid="spelling" attribute.

Supported for all elements.

errorMessage : String -> Html.Styled.Attribute msg

Create an aria-errormessage element.

Reference the element that has error details. e.g., if you've got an input field that's invalid, add errorMessage to the input with the id of whatever element is telling the user in what way their submission is wrong.

import Accessibility.Styled
import Accessibility.Styled.Aria as Aria
import Html.Styled.Attributes exposing (id)

view : List (Html msg)
view =
    [ labelBefore [] (text "Input content:") <|
        inputText "some-content"
            [ Aria.invalid True
            , Aria.errorMessage "error-message-id"
            ]
    , span [ id "error-message-id" ] [ text "Better content required" ]
    ]

You must also use Accessibility.Styled.Aria.invalid when using errorMessage.

Supported by all elements.

pressed : Maybe Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-pressed attribute.

Use pressed when describing a toggle button--a button that can be "toggled" between an on state and an off state (or an on state, an indeterminate state, and an off state).

Please check out these examples as well.

button
    [ pressed <| Just True ]
    [ text "This button should be styled for site viewers such that it's clear it's pressed!" ]

Supported on button.

multiLine : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-multiline attribute.

Indicate whether the textbox is for multi-line inputs or single-line inputs.

Be careful of default keyboard behavior when coupling this property with text inputs, which by default submit their form group on enter.

Supported for textbox only.

checked : Maybe Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-checked attribute.

Check boxes can be checked (Just True), unchecked (Just False), or indeterminate (Nothing).

Available on checkbox, option, radio, switch

selected : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-selected attribute.

Indicate whether an element (in a single- or multi-selectable widget) is or is not selected.

Supported by gridCell, option, row, tab.

indeterminate : Html.Styled.Attribute msg

Creates an aria-indeterminate attribute.

Sets the indeterminate value to be true.

Auto-complete behavior:

See the autocomplete spec.

autoCompleteInline : Html.Styled.Attribute msg

Creates an aria-autocomplete="inline" attribute.

Use when there's a suggestion for completing the field that shows up in the line that the user is completing. Be sure to indicate that the auto-completed text is selected.

Available on comboBox or textbox.

autoCompleteList : Html.Styled.Attribute msg

Creates an aria-autocomplete="list" attribute.

Use when there's a suggestion for completing the field that shows up as a list of options from which the user can pick.

Be sure to indicate that the auto-completed text is selected.

Available on comboBox or textbox.

autoCompleteBoth : Html.Styled.Attribute msg

Creates an aria-autocomplete="both" attribute.

Use when there's a suggestion for completing the field when there's both inline autocomplete and list autocomplete occurring at once.

Be sure to indicate that the auto-completed text is selected.

Available on comboBox or textbox.

Interactability

expanded : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-expanded attribute.

This attribute can be applied to either an element that is itself expanded/collapsed, OR to an elment it controls that is either expanded/collapsed. In the latter case, use a controls attribute as well to clarify the relationship.

Available on button, comboBox, document, link, section, sectionHead, and window.

hidden : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-hidden attribute.

readOnly : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-readonly attribute.

Indicates read-only status of a widget, although normal navigation rules and copying behavior should apply. (Read: readOnly elements are navigable but unchangeable, and disabled elements are neither navigable nor unchangebale).

Supported on checkBox, comboBox, grid, gridCell, listBox, radioGroup, slider, spinButton, and textBox.

disabled : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-disabled attribute.

In deciding whether to use Accessibility.Styled.Aria.disabled or Html.Styled.Attributes.disabled, it may be helpful to read through the Focusablity of disabled controls section of the WAI-ARIA Practices recommendations.

In essence, you may want to use Accessibility.Styled.Aria.disabled instead of Html.Styled.Attributes.disabled if you want users to be aware of disabled elements, and you don't mind that users will need to navigate through these disabled elements.

Supported for all elements. Elements are not disabled (they are enabled) by default.

Pop-Ups

modal : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-modal attribute.

Indicate that a modal is showing and the rest of the page contents are not interactable.

import Accessibility exposing (div, h2, p, text)
import Accessibility.Role exposing (dialog)
import Accessibility.Styled.Aria exposing (labelledBy, modal)
import Html.Attributes exposing (id)

modal : Html msg
modal =
    div [ dialog, modal, labelledBy "header-id" ]
        [ h2 [ id "header-id" ] [ text "Modal Header" ]
        , p [] [ text "Wow, such modal contents!" ]
        ]

hasMenuPopUp : Html.Styled.Attribute msg

Creates an aria-haspopup="menu" attribute.

Indicate that interaction with this element can trigger a menu pop-up.

Be careful while managing focus and triggering.

hasListBoxPopUp : Html.Styled.Attribute msg

Creates an aria-haspopup="listbox" attribute.

Indicate that interaction with this element can trigger a listBox pop-up.

Be careful while managing focus and triggering.

hasTreePopUp : Html.Styled.Attribute msg

Creates an aria-haspopup="tree" attribute.

Indicate that interaction with this element can trigger a tree pop-up.

Be careful while managing focus and triggering.

hasGridPopUp : Html.Styled.Attribute msg

Creates an aria-haspopup="grid" attribute.

Indicate that interaction with this element can trigger a grid pop-up.

Be careful while managing focus and triggering.

hasDialogPopUp : Html.Styled.Attribute msg

Creates an aria-haspopup="dialog" attribute.

Indicate that interaction with this element can trigger a dialog pop-up.

Be careful while managing focus and triggering.

Orientation and Range Widgets

orientationHorizontal : Html.Styled.Attribute msg

Creates an aria-orientation="horizontal attribute.

Supported on roles with some sense of inherent orientation: progressBar, scrollbar, select, separator, slider, tabList, toolBar

Careful: default behavior is inconsistent across those roles.

orientationVertical : Html.Styled.Attribute msg

Creates an aria-orientation="vertical" attribute.

Supported on roles with some sense of inherent orientation: progressBar, scrollbar, select, separator, slider, tabList, toolBar

Careful: default behavior is inconsistent across those roles.

valueMin : Basics.Float -> Html.Styled.Attribute msg

Creates an aria-valuemin attribute.

Set the min allowed value for a range widget.

Supported by progressBar, scrollbar, separator, slider, and spinButton.

valueMax : Basics.Float -> Html.Styled.Attribute msg

Creates an aria-valuemax attribute.

Set the max allowed value for a range widget.

Supported by progressBar, scrollbar, separator, slider, and spinButton.

valueNow : Basics.Float -> Html.Styled.Attribute msg

Creates an aria-valuenow attribute.

Set the current value for a range widget. Don't use this property for indeterminate states.

Supported by progressBar, scrollbar, separator, slider, and spinButton.

valueText : String -> Html.Styled.Attribute msg

Creates an aria-valuetext attribute.

This property takes precedence over valueNow, and should show a human-readable version of the current value. However, valueNow should always be used.

Supported by progressBar, scrollbar, separator, slider, and spinButton.

Table Sort-by-column

sortAscending : Html.Styled.Attribute msg

Creates an aria-sort="ascending" attribute.

Table is sorted by this column's values in ascending order. Only one column in a table should be sorting the values in table.

Supported by columnHeader and rowHeader, but only where those roles are used on table or grid headers.

sortDescending : Html.Styled.Attribute msg

Creates an aria-sort="descending" attribute.

Table is sorted by this column's values in descending order. Only one column in a table should be sorting the values in table.

Supported by columnHeader and rowHeader, but only where those roles are used on table or grid headers.

sortCustom : Html.Styled.Attribute msg

Creates an aria-sort="other" attribute.

Table is sorted by this column's values, but the algorithm for that sorting is custom (not ascending or descending). Only one column in a table should be sorting the values in table.

Supported by columnHeader and rowHeader, but only where those roles are used on table or grid headers.

sortNone : Html.Styled.Attribute msg

Creates an aria-sort="none" attribute.

Table is not sorted by this column's values.

Supported by columnHeader and rowHeader, but only where those roles are used on table or grid headers.

Misc

multiSelectable : Basics.Bool -> Html.Styled.Attribute msg

Creates an aria-multiselectable attribute.

When true, users are not restricted to selecting only one selectable descendant at a time.

Supported on grid, listBox, tabList, tree.

Page Hierarchy

level : Basics.Int -> Html.Styled.Attribute msg

Creates an aria-level attribute.

This attribute is about hierarchy--how many "levels" deep is an element?

h7 attributes =
    div (heading :: level 7 :: attributes)

Supported for grid, heading, listItem, row, and tabList.