Browse Source

web: add tutorial about Controlled and Uncontrolled inputs (#1533)

Co-authored-by: Oleksandr Karpovich <oleksandr.karpovich@jetbrains.com>
pull/1534/head
Oleksandr Karpovich 3 years ago committed by GitHub
parent
commit
b9772b584f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 97
      tutorials/Web/Controlled_Uncontrolled_Inputs/README.md
  2. 2
      tutorials/Web/README.md

97
tutorials/Web/Controlled_Uncontrolled_Inputs/README.md

@ -0,0 +1,97 @@
# Controlled and Uncontrolled inputs
Input components in Compose for Web have two modes: Controlled and Uncontrolled.
### Controlled vs Uncontrolled behaviour
Let's create two inputs using different modes and compare them:
``` kotlin
// Uncontrolled
Input(type = InputType.Text) {
defaultValue("Initial Value") // optional
onInput { event -> println(event.value) }
}
// Controlled
Input(type = InputType.Text) {
value("Some value") // calling value(...) is necessary to make input "Controlled"
onInput { event -> println(event.value) }
}
```
If you try running these snippets you'll see following behaviour:
- Uncontrolled text input will show "Initial value". Typing will make corresponding changes to the input's state.
- Controlled text input will show "Some value". But typing will not cause any changes.
- Both inputs will receive an `event` in `onInput { }` handler
In the example above, we set hardcoded `value` - `value("Some value")`. Therefore, typing does nothing.
Under the hood, controlled input "restores" its state according to last known `value`.
### Using MutableState with Controlled Input
To make Controlled Input more useful we can use `MutableState<*>` to keep input's value:
``` kotlin
val inputState = remember { mutableStateOf("Some Text") }
Input(type = InputType.Text) {
value(inputState.value)
onInput { event -> println(event.value) }
}
```
We can see that, `inputState` never mutates. If we run such an example as is, we'll see the same behaviour
as when `value(...)` was hardcoded. But if we had some code that updates `inputState`, then Input would recompose and new value would be shown.
In most cases, `inputState` needs to be changed in `onInput` event handler:
``` kotlin
val inputState = remember { mutableStateOf("Some Text") }
Input(type = InputType.Text) {
value(inputState.value)
onInput { event -> inputState.value = event.value }
}
```
## Conclusion
Uncontrolled input changes its content independently
while Controlled input's content can be changed only by external state (such as MutableState).
#### In most cases Controlled input is the default choice.
## Convenient controlled inputs
Here is a list of Composable functions which represent controlled inputs of different types:
- CheckboxInput
- DateInput
- DateTimeLocalInput
- EmailInput
- FileInput
- MonthInput
- NumberInput
- PasswordInput
- RadioInput
- RangeInput
- SearchInput
- TelInput
- TextInput
- TimeInput
- UrlInput
- WeekInput
#### Example:
``` kotlin
val inputState = remember { mutableStateOf("Some Text") }
TextInput(value = inputState.value) {
onInput { event -> inputState.value = event.value }
}
```

2
tutorials/Web/README.md

@ -12,6 +12,8 @@ Compose for Web provides multiple ways of declaring user interfaces in Kotlin co
[Handing Events](Events_Handling/README.md) - a short overview of Events handling with compose web
[Controlled and Uncontrolled inputs](Controlled_Uncontrolled_Inputs/README.md) - overview of Controlled and Uncontrolled inputs
[Style DSL](Style_Dsl/README.md) - about styling the composable components in web
[Using test-utils](Using_Test_Utils/README.md) - about unit testing for @Composable components based on HTML DOM

Loading…
Cancel
Save