# semantics

Common/AllAndroid/JVM

## Functions summary

|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/semantics.modifier#(androidx.compose.ui.Modifier).semantics(kotlin.Boolean,kotlin.Function1)(mergeDescendants: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, properties: https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsPropertyReceiver.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Add semantics key/value pairs to the layout node, for use in testing, accessibility, etc. | Cmn |

## Functions

### Modifier.semantics

Cmn Artifact: [androidx.compose.ui:ui](https://developer.android.com/jetpack/androidx/releases/compose-ui) [View Source](https://cs.android.com/search?q=file:androidx/compose/ui/semantics/SemanticsModifier.kt+function:semantics) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.0.0)

```
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 `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsPropertyKey`. Additionally, chaining multiple semantics modifiers is also a supported style.

The resulting semantics produce two `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsNode` trees:

The "unmerged tree" rooted at `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsOwner#unmergedRootSemanticsNode()` has one `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsNode` per layout node which has any `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsModifier` on it. This `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsNode` contains all the properties set in all the `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsModifier`s on that node.

The "merged tree" rooted at `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsOwner#rootSemanticsNode()` has equal-or-fewer nodes: it simplifies the structure based on `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/package-summary#(androidx.compose.ui.Modifier).semantics(kotlin.Boolean,kotlin.Function1)` and `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/clearAndSetSemantics.modifier#(androidx.compose.ui.Modifier).clearAndSetSemantics(kotlin.Function1)`. For most purposes (especially accessibility, or the testing of accessibility), the merged semantics tree should be used.

| Parameters |
|---|---|
| `mergeDescendants: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = 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 `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/package-summary#(androidx.compose.ui.Modifier).semantics(kotlin.Boolean,kotlin.Function1)`) 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 `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsConfiguration#isMergingSemanticsOfDescendants()`. |
| `properties: https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsPropertyReceiver.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | properties to add to the semantics. `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/SemanticsPropertyReceiver` will be provided in the scope to allow access for common properties and its values. Note: The `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/package-summary#(androidx.compose.ui.Modifier).semantics(kotlin.Boolean,kotlin.Function1)` block should be used to set semantic properties or semantic actions. Don't call `https://developer.android.com/reference/kotlin/androidx/compose/ui/node/SemanticsModifierNode#(androidx.compose.ui.semantics.SemanticsPropertyReceiver).applySemantics()` from within the `https://developer.android.com/reference/kotlin/androidx/compose/ui/semantics/package-summary#(androidx.compose.ui.Modifier).semantics(kotlin.Boolean,kotlin.Function1)` block. It will result in an infinite loop. |