semantics
contentDescription, stateDescription and role; see the Document tab.
Open the live, interactive demo →
Change its controls, read the remote document it produces and the diff after every change.
What it is
Describes elements to screen readers and other assistive technology: what they are, what state they are in, what they do.
Good for
- Making every screen accessible
- Labelling icon-only buttons
Code
The story's source with androidx.compose.remote imports. CI compiles every snippet on this site against AndroidX.
import androidx.compose.remote.creation.compose.layout.RemoteAlignment
import androidx.compose.remote.creation.compose.layout.RemoteArrangement
import androidx.compose.remote.creation.compose.layout.RemoteBox
import androidx.compose.remote.creation.compose.layout.RemoteComposable
import androidx.compose.remote.creation.compose.layout.RemoteRow
import androidx.compose.remote.creation.compose.layout.RemoteText
import androidx.compose.remote.creation.compose.modifier.RemoteModifier
import androidx.compose.remote.creation.compose.modifier.RemoteRole
import androidx.compose.remote.creation.compose.modifier.background
import androidx.compose.remote.creation.compose.modifier.clearAndSetSemantics
import androidx.compose.remote.creation.compose.modifier.contentDescription
import androidx.compose.remote.creation.compose.modifier.role
import androidx.compose.remote.creation.compose.modifier.semantics
import androidx.compose.remote.creation.compose.modifier.size
import androidx.compose.remote.creation.compose.modifier.stateDescription
import androidx.compose.remote.creation.compose.state.rc
import androidx.compose.remote.creation.compose.state.rdp
import androidx.compose.remote.creation.compose.state.rs
import androidx.compose.runtime.Composable
import androidx.compose.ui.graphics.Color
@Composable
@RemoteComposable
fun Semantics(description: String, state: String) {
RemoteRow(horizontalArrangement = RemoteArrangement.spacedBy(12.rdp)) {
// semantics adds accessibility properties; see them in the Document tab.
RemoteBox(
RemoteModifier.size(120.rdp, 60.rdp).background(Color(0xFF5C6BC0).rc).semantics {
contentDescription = description.rs
stateDescription = state.rs
role = RemoteRole.Checkbox
},
contentAlignment = RemoteAlignment.Center,
) {
RemoteText("semantics".rs, color = Color.White.rc)
}
// clearAndSetSemantics replaces the children's semantics with its own.
RemoteBox(
RemoteModifier.size(120.rdp, 60.rdp)
.background(Color(0xFF8E24AA).rc)
.clearAndSetSemantics { contentDescription = description.rs },
contentAlignment = RemoteAlignment.Center,
) {
RemoteText("cleared".rs, color = Color.White.rc)
}
}
}
API
creation.compose.modifier.semantics
RemoteModifier semantics(RemoteModifier, optional boolean mergeDescendants, RemoteSemanticsPropertyReceiver.() -> Unit properties)creation.compose.modifier.clearAndSetSemantics
RemoteModifier clearAndSetSemantics(RemoteModifier, RemoteSemanticsPropertyReceiver.() -> Unit properties)creation.compose.modifier.RemoteSemanticsProperties
class RemoteSemanticsProperties
RemoteSemanticsPropertyKey<RemoteString> ContentDescription
RemoteSemanticsPropertyKey<java.lang.Boolean> Enabled
RemoteSemanticsPropertyKey<RemoteRole> Role
RemoteSemanticsPropertyKey<RemoteString> StateDescription
RemoteSemanticsPropertyKey<RemoteString> Text
RemoteSemanticsProperties INSTANCE