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.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.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.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.
label : String -> Html.Attribute msg
Creates an aria-label
attribute.
Supported for all elements.
labelledBy : String -> Html.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.Aria.label
).
labeledBy : String -> Html.Attribute msg
Convenience alias for labelledBy
.
details : String -> Html.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.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.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.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.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.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.
flowTo : List String -> Html.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.
placeholder : String -> Html.Attribute msg
Supported by textbox
and searchbox
.
Provide a hint about an expected value.
Creates an aria-placeholder property.
Generally, you should use Html.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.
scope
or headers
HTML attributes, this is the tutorial for you!colCount : Basics.Int -> Html.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.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.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.Attribute msg
Creates an aria-rowcount
attribute.
Analagous to colcount
.
rowIndex : Basics.Int -> Html.Attribute msg
Creates an aria-rowindex
attribute.
Analagous to colIndex
.
rowSpan : Basics.Int -> Html.Attribute msg
Creates an aria-rowspan
attribute.
Analagous to colSpan
.
setSize : Basics.Int -> Html.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 exposing (..)
import Accessibility.Aria as Aria
import Accessibility.Role as Role
import Html.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.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
.
currentItem : Basics.Bool -> Html.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.Aria.selected
instead.
Supported by all elements.
currentPage : Html.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.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.Attribute msg
Supported by all elements.
currentDate : Html.Attribute msg
Creates an aria-current
attribute, as aria-current=date
.
As in a calendar.
Supported by all elements.
currentTime : Html.Attribute msg
Creates an aria-current
attribute, as aria-current=time
.
As in a timepicker.
Supported by all elements.
required : Basics.Bool -> Html.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.Attribute msg
Creates an aria-invalid
attribute.
Learn more about Using Aria-Invalid to Indicate an Error Field.
You may want to use Accessibility.Aria.errorMessage
or Accessibility.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.Attribute msg
Creates an aria-invalid="grammar"
attribute.
Supported for all elements.
invalidSpelling : Html.Attribute msg
Creates an aria-invalid="spelling"
attribute.
Supported for all elements.
errorMessage : String -> Html.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
import Accessibility.Aria as Aria
import Html.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.Aria.invalid
when using errorMessage
.
Supported by all elements.
pressed : Maybe Basics.Bool -> Html.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.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.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.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.Attribute msg
Creates an aria-indeterminate
attribute.
Sets the indeterminate value to be true.
autoCompleteInline : Html.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.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.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
.
expanded : Basics.Bool -> Html.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.Attribute msg
Creates an aria-hidden
attribute.
readOnly : Basics.Bool -> Html.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.Attribute msg
Creates an aria-disabled
attribute.
In deciding whether to use Accessibility.Aria.disabled
or Html.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.Aria.disabled
instead of Html.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.
modal : Basics.Bool -> Html.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.Aria exposing (labelledBy, modal)
import Accessibility.Role exposing (dialog)
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.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.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.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.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.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.
orientationHorizontal : Html.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.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.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.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.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.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
.
sortAscending : Html.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.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.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.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.
multiSelectable : Basics.Bool -> Html.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
.
level : Basics.Int -> Html.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
.