androidx.compose.ui.semantics

fun Modifier.clearAndSetSemantics(properties: SemanticsPropertyReceiver.() -> Unit): Modifier

Clears the semantics of all the descendant nodes and sets new semantics.

In the merged semantics tree, this clears the semantic information provided by the node's descendants (but not those of the layout node itself, if any) and sets the provided semantics. (In the unmerged tree, the semantics node is marked with "SemanticsConfiguration.isClearingSemantics", but nothing is actually cleared.)

Compose's default semantics provide baseline usability for screen-readers, but this can be used to provide a more polished screen-reader experience: for example, clearing the semantics of a group of tiny buttons, and setting equivalent actions on the card containing them.

fun SemanticsPropertyReceiver.clearTextSubstitution(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to clear the text substitution of this node.

Expected to be used on non-editable text.

fun SemanticsPropertyReceiver.collapse(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to collapse an expandable node.

fun SemanticsPropertyReceiver.copyText(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to copy the text to the clipboard.

fun SemanticsPropertyReceiver.cutText(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to cut the text and copy it to the clipboard.

fun SemanticsPropertyReceiver.dialog(): Unit

Whether this element is a Dialog. Not to be confused with if this element is part of a Dialog.

fun SemanticsPropertyReceiver.disabled(): Unit

Whether this semantics node is disabled. Note that proper SemanticsActions should still be added when this property is set.

fun SemanticsPropertyReceiver.dismiss(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to dismiss a dismissible node.

fun SemanticsPropertyReceiver.error(description: String): Unit

Mark semantics node that contains invalid input or error.

fun SemanticsPropertyReceiver.expand(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to expand an expandable node.

fun SemanticsOwner.getAllSemanticsNodes(
    mergingEnabled: Boolean,
    skipDeactivatedNodes: Boolean = true
): List<SemanticsNode>

Finds all SemanticsNodes in the tree owned by this SemanticsOwner. Return the results in a list.

fun <T : Any?> SemanticsConfiguration.getOrNull(key: SemanticsPropertyKey<T>): T?

fun SemanticsPropertyReceiver.getScrollViewportLength(
    label: String? = null,
    action: () -> Float
): Unit

Action to get a scrollable's active view port amount for scrolling actions.

fun SemanticsPropertyReceiver.getTextLayoutResult(
    label: String? = null,
    action: ((MutableList<TextLayoutResult>) -> Boolean)?
): Unit

Action to get a Text/TextField node's TextLayoutResult. The result is the first element of layout (the argument of the AccessibilityAction).

fun SemanticsPropertyReceiver.heading(): Unit

The node is marked as heading for accessibility.

fun SemanticsPropertyReceiver.hideFromAccessibility(): Unit

If present, this node is considered hidden from accessibility services.

For example, if the node is currently occluded by a dark semitransparent pane above it, then for all practical purposes the node should not be announced to the user. Since the system cannot automatically determine that, this property can be set to make the screen reader linear navigation skip over this type of node.

If looking for a way to clear semantics of small items from the UI tree completely because they are redundant with semantics of their parent, consider SemanticsModifier.clearAndSetSemantics instead.

fun SemanticsPropertyReceiver.indexForKey(mapping: (Any) -> Int): Unit

The index of an item identified by a given key. The key is usually defined during the creation of the container. If the key did not match any of the items' keys, the mapping must return -1.

fun SemanticsPropertyReceiver.insertTextAtCursor(
    label: String? = null,
    action: ((AnnotatedString) -> Boolean)?
): Unit

Action to insert text into this node at the current cursor position, or replacing the selection if text is selected.

Expected to be used on editable text fields.

@ExperimentalComposeUiApi
fun SemanticsPropertyReceiver.invisibleToUser(): Unit

Whether this node is specially known to be invisible to the user.

For example, if the node is currently occluded by a dark semitransparent pane above it, then for all practical purposes the node is invisible to the user, but the system cannot automatically determine that. To make the screen reader linear navigation skip over this type of invisible node, this property can be set.

If looking for a way to hide semantics of small items from screen readers because they're redundant with semantics of their parent, consider SemanticsModifier.clearAndSetSemantics instead.

fun SemanticsPropertyReceiver.onClick(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to be performed when the node is clicked (single-tapped).

fun SemanticsPropertyReceiver.onImeAction(
    imeActionType: ImeAction,
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to invoke the IME action handler configured on the node, as well as specify the type of IME action provided by the node.

Expected to be used on editable text fields.

fun SemanticsPropertyReceiver.onLongClick(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to be performed when the node is long clicked (long-pressed).

fun SemanticsPropertyReceiver.pageDown(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to page down.

Using Role.Carousel will prevent this action from being sent to accessibility services.

fun SemanticsPropertyReceiver.pageLeft(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to page left.

Using Role.Carousel will prevent this action from being sent to accessibility services.

fun SemanticsPropertyReceiver.pageRight(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to page right.

Using Role.Carousel will prevent this action from being sent to accessibility services.

fun SemanticsPropertyReceiver.pageUp(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action to page up.

Using Role.Carousel will prevent this action from being sent to accessibility services.

fun SemanticsPropertyReceiver.password(): Unit

The node is marked as a password.

fun SemanticsPropertyReceiver.pasteText(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

This function adds the SemanticsActions.PasteText to the SemanticsPropertyReceiver. Use it to indicate that element is open for accepting paste data from the clipboard. There is no need to check if the clipboard data available as this is done by the framework. For this action to be triggered, the element must also have the SemanticsProperties.Focused property set.

fun SemanticsPropertyReceiver.performImeAction(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

fun SemanticsPropertyReceiver.popup(): Unit

Whether this semantics node represents a Popup. Not to be confused with if this node is part of a Popup.

fun SemanticsPropertyReceiver.requestFocus(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

Action that gives input focus to this node.

fun SemanticsPropertyReceiver.scrollBy(
    label: String? = null,
    action: ((x: Float, y: Float) -> Boolean)?
): Unit

Action to asynchronously scroll by a specified amount.

scrollByOffset should be preferred in most cases, since it is synchronous and returns the amount of scroll that was actually consumed.

Expected to be used in conjunction with verticalScrollAxisRange/horizontalScrollAxisRange.

fun SemanticsPropertyReceiver.scrollByOffset(
    action: suspend (offset: Offset) -> Offset
): Unit

Action to scroll by a specified amount and return how much of the offset was actually consumed. E.g. if the node can't scroll at all in the given direction, Offset.Zero should be returned. The action should not return until the scroll operation has finished.

Expected to be used in conjunction with verticalScrollAxisRange/horizontalScrollAxisRange.

Unlike scrollBy, this action is synchronous, and returns the amount of scroll consumed.

fun SemanticsPropertyReceiver.scrollToIndex(
    label: String? = null,
    action: (Int) -> Boolean
): Unit

Action to scroll a container to the index of one of its items.

The action should throw an IllegalArgumentException if the index is out of bounds.

fun SemanticsPropertyReceiver.selectableGroup(): Unit

The node is marked as a collection of horizontally or vertically stacked selectable elements.

Unlike collectionInfo which marks a collection of any elements and asks developer to provide all the required information like number of elements etc., this semantics will populate the number of selectable elements automatically. Note that if you use this semantics with lazy collections, it won't get the number of elements in the collection.

fun Modifier.semantics(
    mergeDescendants: Boolean = false,
    properties: SemanticsPropertyReceiver.() -> Unit
): Modifier

Add semantics key/value pairs to the layout node, for use in testing, accessibility, etc.

The provided lambda receiver scope provides "key = value"-style setters for any SemanticsPropertyKey. Additionally, chaining multiple semantics modifiers is also a supported style.

The resulting semantics produce two SemanticsNode trees:

The "unmerged tree" rooted at SemanticsOwner.unmergedRootSemanticsNode has one SemanticsNode per layout node which has any SemanticsModifier on it. This SemanticsNode contains all the properties set in all the SemanticsModifiers on that node.

The "merged tree" rooted at SemanticsOwner.rootSemanticsNode has equal-or-fewer nodes: it simplifies the structure based on mergeDescendants and clearAndSetSemantics. For most purposes (especially accessibility, or the testing of accessibility), the merged semantics tree should be used.

fun SemanticsPropertyReceiver.setProgress(
    label: String? = null,
    action: ((Float) -> Boolean)?
): Unit

Action to set the current value of the progress bar.

Expected to be used in conjunction with progressBarRangeInfo.

fun SemanticsPropertyReceiver.setSelection(
    label: String? = null,
    action: ((startIndex: Int, endIndex: Int, relativeToOriginalText: Boolean) -> Boolean)?
): Unit

Action to set text selection by character index range.

If this action is provided, the selection data must be provided using textSelectionRange.

fun SemanticsPropertyReceiver.setText(
    label: String? = null,
    action: ((AnnotatedString) -> Boolean)?
): Unit

Action to set the text contents of this node.

Expected to be used on editable text fields.

fun SemanticsPropertyReceiver.setTextSubstitution(
    label: String? = null,
    action: ((AnnotatedString) -> Boolean)?
): Unit

Action to set the text substitution of this node.

Expected to be used on non-editable text.

Note, this action doesn't show the text substitution. Please call SemanticsPropertyReceiver.showTextSubstitution to show the text substitution.

fun SemanticsPropertyReceiver.showTextSubstitution(
    label: String? = null,
    action: ((Boolean) -> Boolean)?
): Unit

Action to show or hide the text substitution of this node.

Expected to be used on non-editable text.

Note, this action only takes effect when the node has the text substitution.

var SemanticsPropertyReceiver.collectionInfo: CollectionInfo

This semantics marks node as a collection and provides the required information.

var SemanticsPropertyReceiver.collectionItemInfo: CollectionItemInfo

This semantics marks node as an items of a collection and provides the required information.

If you mark items of a collection, you should also be marking the collection with collectionInfo.

var SemanticsPropertyReceiver.contentDescription: String

Developer-set content description of the semantics node.

If this is not set, accessibility services will present the text of this node as the content.

This typically should not be set directly by applications, because some screen readers will cease presenting other relevant information when this property is present. This is intended to be used via Foundation components which are inherently intractable to automatically describe, such as Image, Icon, and Canvas.

var SemanticsPropertyReceiver.customActions: List<CustomAccessibilityAction>

Custom actions which are defined by app developers.

var SemanticsPropertyReceiver.editableText: AnnotatedString

Input text of the text field with visual transformation applied to it. It must be a real text entered by the user with visual transformation applied on top of the input text instead of a developer-set content description.

var SemanticsPropertyReceiver.focused: Boolean

Whether this semantics node is focused. The presence of this property indicates this node is focusable

var SemanticsPropertyReceiver.horizontalScrollAxisRange: ScrollAxisRange

The horizontal scroll state of this node if this node is scrollable.

var SemanticsPropertyReceiver.imeAction: ImeAction

Contains the IME action provided by the node.

For example, "go to next form field" or "submit".

A node that specifies an action should also specify a callback to perform the action via onImeAction.

var SemanticsPropertyReceiver.isContainer: Boolean

Whether this semantics node is a container. This is defined as a node whose function is to serve as a boundary or border in organizing its children.

var SemanticsPropertyReceiver.isEditable: Boolean

Whether this semantics node is editable, e.g. an editable text field.

var SemanticsPropertyReceiver.isShowingTextSubstitution: Boolean

Whether this element is showing the text substitution. This property is only available after calling SemanticsActions.SetTextSubstitution.

var SemanticsPropertyReceiver.isTraversalGroup: Boolean

Whether this semantics node is a traversal group.

See https://developer.android.com/jetpack/compose/accessibility#modify-traversal-order

var SemanticsPropertyReceiver.liveRegion: LiveRegionMode

This node is marked as live region for accessibility. This indicates to accessibility services they should automatically notify the user about changes to the node's content description or text, or to the content descriptions or text of the node's children (where applicable). It should be used with caution, especially with assertive mode which immediately stops the current audio and the user does not hear the rest of the content. An example of proper use is a Snackbar which is marked as LiveRegionMode.Polite.

var SemanticsPropertyReceiver.maxTextLength: Int

Limits the number of characters that can be entered, e.g. in an editable text field. By default this value is -1, signifying there is no maximum text length limit.

var SemanticsPropertyReceiver.paneTitle: String

Accessibility-friendly title for a screen's pane. For accessibility purposes, a pane is a visually distinct portion of a window, such as the contents of a open drawer. In order for accessibility services to understand a pane's window-like behavior, you should give descriptive titles to your app's panes. Accessibility services can then provide more granular information to users when a pane's appearance or content changes.

var SemanticsPropertyReceiver.progressBarRangeInfo: ProgressBarRangeInfo

The semantics represents a range of possible values with a current value. For example, when used on a slider control, this will allow screen readers to communicate the slider's state.

var SemanticsPropertyReceiver.role: Role

The type of user interface element. Accessibility services might use this to describe the element or do customizations. Most roles can be automatically resolved by the semantics properties of this element. But some elements with subtle differences need an exact role. If an exact role is not listed in Role, this property should not be set and the framework will automatically resolve it.

var SemanticsPropertyReceiver.selected: Boolean

Whether this element is selected (out of a list of possible selections).

The presence of this property indicates that the element is selectable.

var SemanticsPropertyReceiver.stateDescription: String

Developer-set state description of the semantics node.

For example: on/off. If this not set, accessibility services will derive the state from other semantics properties, like ProgressBarRangeInfo, but it is not guaranteed and the format will be decided by accessibility services.

var SemanticsPropertyReceiver.testTag: String

Test tag attached to this semantics node.

This can be used to find nodes in testing frameworks:

• In Compose's built-in unit test framework, use with onNodeWithTag.

• For newer AccessibilityNodeInfo-based integration test frameworks, it can be matched in the extras with key "androidx.compose.ui.semantics.testTag"

• For legacy AccessibilityNodeInfo-based integration tests, it's optionally exposed as the resource id if testTagsAsResourceId is true (for matching with 'By.res' in UIAutomator).

var SemanticsPropertyReceiver.testTagsAsResourceId: Boolean

Configuration toggle to map testTags to resource-id.

This provides a way of filling in AccessibilityNodeInfo.viewIdResourceName, which in the View System is populated based on the resource string in the XML.

testTags are also provided in AccessibilityNodeInfo.extras under key "androidx.compose.ui.semantics.testTag". However, when using UIAutomator or on Android 7 and below, extras are not available, so a more backwards-compatible way of making testTags available to accessibility-tree-based integration tests is sometimes needed. resource-id was the most natural property to repurpose for this.

This property applies to a semantics subtree. For example, if it's set to true on the root semantics node of the app (and no child nodes set it back to false), then every testTag will be mapped.

var SemanticsPropertyReceiver.text: AnnotatedString

Text of the semantics node. It must be real text instead of developer-set content description.

var SemanticsPropertyReceiver.textSelectionRange: TextRange

Text selection range for the text field.

var SemanticsPropertyReceiver.textSubstitution: AnnotatedString

Text substitution of the semantics node. This property is only available after calling SemanticsActions.SetTextSubstitution.

var SemanticsPropertyReceiver.toggleableState: ToggleableState

The state of a toggleable component.

The presence of this property indicates that the element is toggleable.

var SemanticsPropertyReceiver.traversalIndex: Float

A value to manually control screenreader traversal order.

This API can be used to customize TalkBack traversal order. When the traversalIndex property is set on a traversalGroup or on a screenreader-focusable node, then the sorting algorithm will prioritize nodes with smaller traversalIndexs earlier. The default traversalIndex value is zero, and traversalIndices are compared at a peer level.

For example,traversalIndex = -1f can be used to force a top bar to be ordered earlier, and traversalIndex = 1f to make a bottom bar ordered last, in the edge cases where this does not happen by default. As another example, if you need to reorder two Buttons within a Row, then you can set isTraversalGroup = true on the Row, and set traversalIndex on one of the Buttons.

Note that if traversalIndex seems to have no effect, be sure to set isTraversalGroup = true as well.

var SemanticsPropertyReceiver.verticalScrollAxisRange: ScrollAxisRange

The vertical scroll state of this node if this node is scrollable.