Input

Updated: Oct 7, 2024

Overview

Input components allow users to enter text using the system’s virtual keyboard or other input methods. The Meta Horizon OS UI Set provides input components adapted for spatial UIs.

Text field (`SpatialTextField`)

Standard input field for entering single or multi-line text, often used in forms.

Composable: SpatialTextField

Usage: Usernames, passwords, messages, descriptions, generic text input.

Key Parameters:

value: String: The current text content.

onValueChange: (String) -> Unit: Callback invoked when the text changes.

label: String: Text label displayed above the field.

modifier: Modifier

placeholder: String?: Hint text displayed inside the field when empty.

helperText: String?: Additional text displayed below the field (can indicate errors or provide guidance).

enabled: Boolean = true: Controls interactability.

leadingIcon: @Composable (() -> Unit)?: Optional icon before the text input area.

trailingIcon: @Composable (() -> Unit)?: Optional icon after the text input area (often used for validation status or clear buttons).

singleLine: Boolean = true: If true, restricts input to a single line and often shows a “Done” action on the keyboard. If false, allows multiple lines and may show a newline action.

validationPredicate: ((String) -> Flow<FieldValidationState>)?: Optional asynchronous validation logic.

initialState: FieldValidationState = FieldValidationState.Unspecified: Initial validation state.

autoValidate: Boolean = true: If true and validationPredicate is provided, validation runs automatically on value change.

keyboardOptions: Standard Compose KeyboardOptions (for example, keyboardType, imeAction, capitalization, autoCorrect).

keyboardActions: Standard Compose KeyboardActions (for example, onDone, onSend).

Validation:

Uses FieldValidationState enum (Valid, Invalid, Validating, Unspecified).

If autoValidate is true, the border color and trailing icon can change based on the state emitted by the validationPredicate flow. Helper text color also adapts to Valid/Invalid states.

import com.meta.spatial.uiset.input.SpatialTextField
import com.meta.spatial.uiset.input.foundation.FieldValidationState
import androidx.compose.runtime.*
import androidx.compose.material3.Icon
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.flow

var username by remember { mutableStateOf("") }
var password by remember { mutableStateOf("") }
var description by remember { mutableStateOf("") }
var validationState by remember { mutableStateOf(FieldValidationState.Unspecified) }


// Basic TextField
SpatialTextField(
    value = username,
    onValueChange = { username = it },
    label = "Username",
    placeholder = "Enter your username",
    singleLine = true
)

Spacer(Modifier.height(16.dp))

// TextField with validation
SpatialTextField(
    value = password,
    onValueChange = { password = it },
    label = "Password",
    placeholder = "Enter password",
    singleLine = true,
    keyboardType = KeyboardType.Password,
    autoValidate = true,
    initialState = validationState, // Pass state if managed externally
    validationPredicate = { input ->
        flow {
            emit(FieldValidationState.Validating)
            delay(500) // Simulate network check
            if (input.length >= 8) {
                emit(FieldValidationState.Valid)
            } else {
                emit(FieldValidationState.Invalid)
            }
        }
    },
    helperText = when (validationState) { // Example dynamic helper text
        FieldValidationState.Invalid -> "Password must be at least 8 characters"
        else -> null
    }
)


Spacer(Modifier.height(16.dp))

// Multi-line TextField with Icon
SpatialTextField(
    value = description,
    onValueChange = { description = it },
    label = "Description",
    placeholder = "Tell us about yourself...",
    singleLine = false, // Allow multiple lines
    leadingIcon = { Icon(SpatialIcons.Regular.Info, null) },
    modifier = Modifier.height(120.dp) // Example height constraint
)

Search bar (`SpatialSearchBar`)

A specialized input field optimized for search queries.

Composable: SpatialSearchBar

Usage: Entering search terms.

Key Parameters:

query: String: The current search text.

onQueryChange: (String) -> Unit: Callback when the text changes.

onQuerySubmit: (String) -> Unit: Callback when the search is submitted (for example, user presses “Done” on keyboard).

modifier: Modifier

placeholder: String = "Search": Default placeholder text.

enableAudio: Boolean = false: If true, shows a microphone icon that toggles for potential voice input (actual voice input mechanism not implemented in the component itself, only the toggle visual).

enabled: Boolean = true

keyboardOptions, keyboardActions: Similar to SpatialTextField, typically configured for ImeAction.Search or Done.

import com.meta.spatial.uiset.input.SpatialSearchBar
import androidx.compose.runtime.*

var searchQuery by remember { mutableStateOf("") }

SpatialSearchBar(
    query = searchQuery,
    onQueryChange = { searchQuery = it },
    onQuerySubmit = { submittedQuery ->
        println("Search submitted: $submittedQuery")
        // Trigger search logic
    },
    placeholder = "Search for apps..."
)

Spacer(Modifier.height(16.dp))

// Search bar with audio toggle visual
SpatialSearchBar(
    query = searchQuery,
    onQueryChange = { searchQuery = it },
    onQuerySubmit = { /* ... */ },
    enableAudio = true
)

Both components integrate with the system virtual keyboard when focused within a spatial panel. Use SpatialTextField for general input and SpatialSearchBar for search-specific scenarios.

Did you find this page helpful?