androidx.compose.ui.semantics

In this page, you'll find documentation for types, properties, and functions available in the androidx.compose.ui.semantics package such as semantics, clearAndSetSemantics, customActions, and testTag.

If you're looking for guidance instead, check out the following Compose guides:

Interfaces

SemanticsModifier

A Modifier.Element that adds semantics key/value for use in testing, accessibility, and similar use cases.
Cmn
SemanticsPropertyReceiver

SemanticsPropertyReceiver is the scope provided by semantics {} blocks, letting you set key/value pairs primarily via extension functions.
Cmn

Classes

AccessibilityAction

Standard accessibility action.
Cmn
CollectionInfo

Information about the collection.
Cmn
CollectionItemInfo

Information about the item of a collection.
Cmn
CustomAccessibilityAction

Custom accessibility action.
Cmn
LiveRegionMode

The mode of live region.
Cmn
ProgressBarRangeInfo

Accessibility range information, to represent the status of a progress bar or seekable progress bar.
Cmn
Role

The type of user interface element.
Cmn
ScrollAxisRange

The scroll state of one axis if this node is scrollable.
Cmn
SemanticsConfiguration

Describes the semantic information associated with the owning component
Cmn
SemanticsNode

A list of key/value pairs associated with a layout node or its subtree.
Cmn
SemanticsOwner

Owns SemanticsNode objects and notifies listeners of changes to the semantics tree
Cmn
SemanticsPropertyKey

SemanticsPropertyKey is the infrastructure for setting key/value pairs inside semantics blocks in a type-safe way.
Cmn

Objects

SemanticsActions

Ths object defines keys of the actions which can be set in semantics and performed on the semantics node.
Cmn
SemanticsProperties

General semantics properties, mainly used for accessibility and testing.
Cmn
SemanticsPropertiesAndroid
android

Extension functions summary

Modifier

Clears the semantics of all the descendant nodes and sets new semantics.
Cmn
Unit
SemanticsPropertyReceiver.clearTextSubstitution(
    label: String?,
    action: (() -> Boolean)?
)

Action to clear the text substitution of this node.
Cmn
Unit
SemanticsPropertyReceiver.collapse(label: String?, action: (() -> Boolean)?)

Action to collapse an expandable node.
Cmn
Unit
SemanticsPropertyReceiver.copyText(label: String?, action: (() -> Boolean)?)

Action to copy the text to the clipboard.
Cmn
Unit
SemanticsPropertyReceiver.cutText(label: String?, action: (() -> Boolean)?)

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

Whether this element is a Dialog.
Cmn
Unit

Whether this semantics node is disabled.
Cmn
Unit
SemanticsPropertyReceiver.dismiss(label: String?, action: (() -> Boolean)?)

Action to dismiss a dismissible node.
Cmn
Unit

Mark semantics node that contains invalid input or error.
Cmn
Unit
SemanticsPropertyReceiver.expand(label: String?, action: (() -> Boolean)?)

Action to expand an expandable node.
Cmn
List<SemanticsNode>
SemanticsOwner.getAllSemanticsNodes(
    mergingEnabled: Boolean,
    skipDeactivatedNodes: Boolean
)

Finds all SemanticsNodes in the tree owned by this SemanticsOwner.
Cmn
T?
Cmn
Unit
SemanticsPropertyReceiver.getScrollViewportLength(
    label: String?,
    action: () -> Float
)

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

Action to get a Text/TextField node's TextLayoutResult.
Cmn
Unit

The node is marked as heading for accessibility.
Cmn
Unit

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

The index of an item identified by a given key.
Cmn
Unit

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

This function is deprecated. Use `hideFromAccessibility()` instead.
Cmn
Unit
SemanticsPropertyReceiver.onAutofillText(
    label: String?,
    action: ((AnnotatedString) -> Boolean)?
)

Action to autofill a TextField.
Cmn
Unit
SemanticsPropertyReceiver.onClick(label: String?, action: (() -> Boolean)?)

Action to be performed when the node is clicked (single-tapped).
Cmn
Unit
SemanticsPropertyReceiver.onImeAction(
    imeActionType: ImeAction,
    label: String?,
    action: (() -> Boolean)?
)

Action to invoke the IME action handler configured on the node, as well as specify the type of IME action provided by the node.
Cmn
Unit
SemanticsPropertyReceiver.onLongClick(
    label: String?,
    action: (() -> Boolean)?
)

Action to be performed when the node is long clicked (long-pressed).
Cmn
Unit
SemanticsPropertyReceiver.pageDown(label: String?, action: (() -> Boolean)?)

Action to page down.
Cmn
Unit
SemanticsPropertyReceiver.pageLeft(label: String?, action: (() -> Boolean)?)

Action to page left.
Cmn
Unit
SemanticsPropertyReceiver.pageRight(label: String?, action: (() -> Boolean)?)

Action to page right.
Cmn
Unit
SemanticsPropertyReceiver.pageUp(label: String?, action: (() -> Boolean)?)

Action to page up.
Cmn
Unit

The node is marked as a password.
Cmn
Unit
SemanticsPropertyReceiver.pasteText(label: String?, action: (() -> Boolean)?)

This function adds the SemanticsActions.PasteText to the SemanticsPropertyReceiver.
Cmn
Unit
SemanticsPropertyReceiver.performImeAction(
    label: String?,
    action: (() -> Boolean)?
)

This function is deprecated. Use `SemanticsPropertyReceiver.onImeAction` instead.
Cmn
Unit

Whether this semantics node represents a Popup.
Cmn
Unit
SemanticsPropertyReceiver.requestFocus(
    label: String?,
    action: (() -> Boolean)?
)

Action that gives input focus to this node.
Cmn
Unit
SemanticsPropertyReceiver.scrollBy(
    label: String?,
    action: ((x: Float, y: Float) -> Boolean)?
)

Action to asynchronously scroll by a specified amount.
Cmn
Unit
SemanticsPropertyReceiver.scrollByOffset(
    action: suspend (offset: Offset) -> Offset
)

Action to scroll by a specified amount and return how much of the offset was actually consumed.
Cmn
Unit
SemanticsPropertyReceiver.scrollToIndex(
    label: String?,
    action: (Int) -> Boolean
)

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

The node is marked as a collection of horizontally or vertically stacked selectable elements.
Cmn
Modifier
Modifier.semantics(mergeDescendants: Boolean, properties: SemanticsPropertyReceiver.() -> Unit)

Add semantics key/value pairs to the layout node, for use in testing, accessibility, etc.
Cmn
Unit
SemanticsPropertyReceiver.setProgress(
    label: String?,
    action: ((Float) -> Boolean)?
)

Action to set the current value of the progress bar.
Cmn
Unit
SemanticsPropertyReceiver.setSelection(
    label: String?,
    action: ((startIndex: Int, endIndex: Int, relativeToOriginalText: Boolean) -> Boolean)?
)

Action to set text selection by character index range.
Cmn
Unit
SemanticsPropertyReceiver.setText(
    label: String?,
    action: ((AnnotatedString) -> Boolean)?
)

Action to set the text contents of this node.
Cmn
Unit

Action to set the text substitution of this node.
Cmn
Unit
SemanticsPropertyReceiver.showTextSubstitution(
    label: String?,
    action: ((Boolean) -> Boolean)?
)

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

Extension properties summary

CollectionInfo

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

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

Content data type information.
Cmn
String

Developer-set content description of the semantics node.
Cmn
ContentType

Content field type information.
Cmn
List<CustomAccessibilityAction>

Custom actions which are defined by app developers.
Cmn
AnnotatedString

Input text of the text field with visual transformation applied to it.
Cmn
Boolean

Whether this semantics node is focused.
Cmn
ScrollAxisRange

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

This property is deprecated. Pass the ImeAction to onImeAction instead.
Cmn
Boolean

This property is deprecated. Use `isTraversalGroup` instead.
Cmn
Boolean

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

Whether this element is showing the text substitution.
Cmn
Boolean

Whether this semantics node is a traversal group.
Cmn
LiveRegionMode

This node is marked as live region for accessibility.
Cmn
Int

Limits the number of characters that can be entered, e.g. in an editable text field.
Cmn
String

Accessibility-friendly title for a screen's pane.
Cmn
ProgressBarRangeInfo

The semantics represents a range of possible values with a current value.
Cmn
Role

The type of user interface element.
Cmn
Boolean

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

Developer-set state description of the semantics node.
Cmn
String

Test tag attached to this semantics node.
Cmn
Boolean

Configuration toggle to map testTags to resource-id.
android
AnnotatedString

Text of the semantics node.
Cmn
TextRange

Text selection range for the text field.
Cmn
AnnotatedString

Text substitution of the semantics node.
Cmn
ToggleableState

The state of a toggleable component.
Cmn
Float

A value to manually control screenreader traversal order.
Cmn
ScrollAxisRange

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

Extension functions

clearAndSetSemantics

Cmn 
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.

Parameters
properties: SemanticsPropertyReceiver.() -> Unit

properties to add to the semantics. SemanticsPropertyReceiver will be provided in the scope to allow access for common properties and its values.

clearTextSubstitution

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when SemanticsActions.ClearTextSubstitution is called.

collapse

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

Action to collapse an expandable node.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.Collapse is called.

copyText

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

Action to copy the text to the clipboard.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.CopyText is called.

cutText

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

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

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.CutText is called.

dialog

Cmn 
fun SemanticsPropertyReceiver.dialog(): Unit

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

disabled

Cmn 
fun SemanticsPropertyReceiver.disabled(): Unit

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

See also
Disabled

dismiss

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

Action to dismiss a dismissible node.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.Dismiss is called.

error

Cmn 
fun SemanticsPropertyReceiver.error(description: String): Unit

Mark semantics node that contains invalid input or error.

Parameters
description: String

a localized description explaining an error to the accessibility user

expand

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

Action to expand an expandable node.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.Expand is called.

getAllSemanticsNodes

Cmn 
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.

Parameters
mergingEnabled: Boolean

set to true if you want the data to be merged.
skipDeactivatedNodes: Boolean = true

set to false if you want to collect the nodes which are deactivated. For example, the children of androidx.compose.ui.layout.SubcomposeLayout which are retained to be reused in future are considered deactivated.

getOrNull

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

getScrollViewportLength

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

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

Parameters
label: String? = null

Optional label for this action.
action: () -> Float

Action to be performed when the SemanticsActions.GetScrollViewportLength is called.

getTextLayoutResult

Cmn 
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).

Parameters
label: String? = null

Optional label for this action.
action: ((MutableList<TextLayoutResult>) -> Boolean)?

Action to be performed when the SemanticsActions.GetTextLayoutResult is called.

heading

Cmn 
fun SemanticsPropertyReceiver.heading(): Unit

The node is marked as heading for accessibility.

See also
Heading

hideFromAccessibility

Cmn 
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.

indexForKey

Cmn 
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.

insertTextAtCursor

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: ((AnnotatedString) -> Boolean)?

Action to be performed when SemanticsActions.InsertTextAtCursor is called.

invisibleToUser

Cmn
Added in 1.0.0
Deprecated in 1.8.0-alpha05
@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.

onAutofillText

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

Action to autofill a TextField.

Expected to be used in conjunction with contentType and contentDataType properties.

Parameters
label: String? = null

Optional label for this action.
action: ((AnnotatedString) -> Boolean)?

Action to be performed when the SemanticsActions.OnAutofillText is called.

onClick

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

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

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.OnClick is called.

onImeAction

Cmn 
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.

Parameters
imeActionType: ImeAction

The IME type, such as ImeAction.Next or ImeAction.Search
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when SemanticsActions.OnImeAction is called.
See also
ImeAction
OnImeAction

onLongClick

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

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

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.OnLongClick is called.

pageDown

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.PageDown is called.
See also
Carousel

for more information.

pageLeft

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.PageLeft is called.
See also
Carousel

for more information.

pageRight

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.PageRight is called.
See also
Carousel

for more information.

pageUp

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.PageUp is called.
See also
Carousel

for more information.

password

Cmn 
fun SemanticsPropertyReceiver.password(): Unit

The node is marked as a password.

pasteText

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.PasteText is called.
See also
focused

performImeAction

Cmn
Added in 1.7.0
Deprecated in 1.7.0
fun SemanticsPropertyReceiver.performImeAction(
    label: String? = null,
    action: (() -> Boolean)?
): Unit

popup

Cmn 
fun SemanticsPropertyReceiver.popup(): Unit

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

requestFocus

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

Action that gives input focus to this node.

Parameters
label: String? = null

Optional label for this action.
action: (() -> Boolean)?

Action to be performed when the SemanticsActions.RequestFocus is called.

scrollBy

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: ((x: Float, y: Float) -> Boolean)?

Action to be performed when SemanticsActions.ScrollBy is called.

scrollByOffset

Cmn 
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.

Parameters
action: suspend (offset: Offset) -> Offset

Action to be performed when SemanticsActions.ScrollByOffset is called.

scrollToIndex

Cmn 
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.

selectableGroup

Cmn 
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.

See also
selected

semantics

Cmn 
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.

Parameters
mergeDescendants: Boolean = false

Whether the semantic information provided by the owning component and its descendants should be treated as one logical entity. Most commonly set on screen-reader-focusable items such as buttons or form fields. In the merged semantics tree, all descendant nodes (except those themselves marked mergeDescendants) will disappear from the tree, and their properties will get merged into the parent's configuration (using a merging algorithm that varies based on the type of property -- for example, text properties will get concatenated, separated by commas). In the unmerged semantics tree, the node is simply marked with SemanticsConfiguration.isMergingSemanticsOfDescendants.
properties: SemanticsPropertyReceiver.() -> Unit

properties to add to the semantics. SemanticsPropertyReceiver will be provided in the scope to allow access for common properties and its values.

setProgress

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: ((Float) -> Boolean)?

Action to be performed when the SemanticsActions.SetProgress is called.

setSelection

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: ((startIndex: Int, endIndex: Int, relativeToOriginalText: Boolean) -> Boolean)?

Action to be performed when the SemanticsActions.SetSelection is called. The parameters to the action are: startIndex, endIndex, and whether the indices are relative to the original text or the transformed text (when a VisualTransformation is applied).

setText

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: ((AnnotatedString) -> Boolean)?

Action to be performed when SemanticsActions.SetText is called.

setTextSubstitution

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: ((AnnotatedString) -> Boolean)?

Action to be performed when SemanticsActions.SetTextSubstitution is called.

showTextSubstitution

Cmn 
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.

Parameters
label: String? = null

Optional label for this action.
action: ((Boolean) -> Boolean)?

Action to be performed when SemanticsActions.ShowTextSubstitution is called.

Extension properties

collectionInfo

Cmn 
var SemanticsPropertyReceiver.collectionInfo: CollectionInfo

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

See also
collectionItemInfo

collectionItemInfo

Cmn 
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.

contentDataType

Cmn 
var SemanticsPropertyReceiver.contentDataType: ContentDataType

Content data type information.

This API can be used to indicate to Autofill services what kind of data is meant to be suggested for this field. Not to be confused with the type of the field.

See also
ContentType

contentDescription

Cmn 
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.

contentType

Cmn 
var SemanticsPropertyReceiver.contentType: ContentType

Content field type information.

This API can be used to indicate to Autofill services what kind of field is associated with this node. Not to be confused with the data type to be entered into the field.

See also
ContentType

customActions

Cmn 
var SemanticsPropertyReceiver.customActions: List<CustomAccessibilityAction>

Custom actions which are defined by app developers.

editableText

Cmn 
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.

focused

Cmn 
var SemanticsPropertyReceiver.focused: Boolean

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

See also
Focused

horizontalScrollAxisRange

Cmn 
var SemanticsPropertyReceiver.horizontalScrollAxisRange: ScrollAxisRange

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

imeAction

Cmn
Added in 1.0.0
Deprecated in 1.5.0
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.

isContainer

Cmn
Added in 1.4.0
Deprecated in 1.5.0
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.

See also
IsContainer

isEditable

Cmn 
var SemanticsPropertyReceiver.isEditable: Boolean

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

isShowingTextSubstitution

Cmn 
var SemanticsPropertyReceiver.isShowingTextSubstitution: Boolean

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

isTraversalGroup

Cmn 
var SemanticsPropertyReceiver.isTraversalGroup: Boolean

Whether this semantics node is a traversal group.

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

See also
IsTraversalGroup

liveRegion

Cmn 
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.

See also
LiveRegion
LiveRegionMode

maxTextLength

Cmn 
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.

paneTitle

Cmn 
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.

See also
PaneTitle

progressBarRangeInfo

Cmn 
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.

role

Cmn 
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.

selected

Cmn 
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.

stateDescription

Cmn 
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.

testTag

Cmn 
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).

testTagsAsResourceId

android 
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.

text

Cmn 
var SemanticsPropertyReceiver.text: AnnotatedString

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

See also
editableText

textSelectionRange

Cmn 
var SemanticsPropertyReceiver.textSelectionRange: TextRange

Text selection range for the text field.

textSubstitution

Cmn 
var SemanticsPropertyReceiver.textSubstitution: AnnotatedString

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

toggleableState

Cmn 
var SemanticsPropertyReceiver.toggleableState: ToggleableState

The state of a toggleable component.

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

traversalIndex

Cmn 
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.

verticalScrollAxisRange

Cmn 
var SemanticsPropertyReceiver.verticalScrollAxisRange: ScrollAxisRange

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