---
title: "semantics"
description: "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 [SemanticsModifier]s 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.

 Note: The [properties] block should be used to set semantic properties or semantic actions. Don't call [SemanticsModifierNode.applySemantics] from within the [properties] block. It will result in an infinite loop."
type: "modifier"
---

<div class='type'>Compose Modifier</div>

<a id='references'></a>
<div class='sourceset sourceset-common'>Common</div>


```kotlin
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 `SemanticsModifier`s 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.

 Note: The `properties` block should be used to set semantic properties or semantic actions. Don't call `SemanticsModifierNode.applySemantics` from within the `properties` block. It will result in an infinite loop.

#### Parameters

| | |
| --- | --- |
| mergeDescendants | 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 | properties to add to the semantics. `SemanticsPropertyReceiver` will be provided in the scope to allow access for common properties and its values. |