When updating a fragment you may control how Unpoly moves focus by passing
a { focus }
option or [up-focus]
attribute.
Changing the focus will make a screen reader start reading from the focused position.
When navigating Unpoly will default to
{ focus: 'auto' }
.
Pass 'target
' to focus the new fragment.
Pass 'layer
' to focus the layer of the updated fragment.
Pass a CSS selector string to focus a matching element.
From JavaScript you may also pass the Element
object that should be focused.
If the element isn't already focusable, Unpoly will give it an [tabindex=-1]
attribute.
Pass 'keep'
to preserve focus-related element properties.
When the focused fragment is rediscovered in the new content, the following properties are preserved:
Pass 'layer'
to focus the container element of the updated layer.
Pass 'reset'
to restore the last known focus positions for the updated layer's URL.
Unpoly will automatically save focus positions before a fragment update.
You may disable this behavior with { saveFocus: false }
.
#hash
targetPass 'hash'
to focus the element matching the #hash
in the URL.
Pass 'main'
to reveal the updated layer's main element.
Pass false
to keep all focus positions.
To only focus when a main target is updated,
you may append -if-main
to any of the string options in this list.
E.g. 'reset-if-main'
will reset focus positions, but only if a main target is updated.
To only focus when the focus was lost with the old fragment,
you may append -if-list
to any of the string options in this list.
E.g. 'target-if-lost'
will focus the new fragment, but only if the update caused focus
to be lost.
To implement other conditions, pass a function instead.
Pass an array of focus option and Unpoly will use the first applicable value.
E.g. ['hash', 'reset']
will first try to an element mathing the #hash
in the URL.
If the URL has no #hash
, focus positions will be reset.
Pass 'auto'
to try a sequence of focus strategies that works for most cases.
This is the default when navigating.
#hash
in the URL.[autofocus]
element in the new fragment.You may configure this logic in up.fragment.config.autoFocus
.
You may also pass a function with your custom focusing logic.
The function will be called with the updated fragment and an options object. The function is expected to either:
{ scroll }
option.
Both Element#focus()
and up.focus()
accept a { preventScroll: true }
option
to prevent scrolling.