useCloudState

useCloudState is used to read and write data to a specific path in your user state.
Basic Usage
1
import { client } from "./src/utils/cloudState.js";
2
​
3
const path = "user.name"
4
const defaultValue = ""
5
​
6
function HelloWorld() {
7
 const [data, setData] = client.hooks.useCloudState(path, defaultValue);
8
​
9
 return (
10
 <div className="HelloWorld">
11
 <input
12
 type="text"
13
 value={data}
14
 onChange={e => setData(e.target.value)}
15
 />
16
 <p>Welcome to my app, {name}!</p>
17
 </div>
18
 )
19
}
Copied!
Parameters
path
The key that this piece of state is identified by. This is explained in detail here.
defaultValue
The value that is displayed if the stored value is unset or being loaded.
path Parameter Behaviour
path is a string that tells the server where to save that specific piece of data. You can even access the same piece of data and change it from another component, if you give the same path name.
We recommend that you give decriptive and specific names to your path identifier.
Structured paths
If you want to create deeply nested paths that contain multiple pieces of data, you can do it via the dot (.) notation.
Suppose, you have a NameForm component where you want to get a user's first and last names, and a DisplayName component where you want to display the full name.
1
function NameForm() {
2
 const [firstName, setFirstName] = client.hooks.useCloudState("user.name.first", "");
3
 const [lastName, setLastName] = client.hooks.useCloudState("user.name.last", "");
4
​
5
 return (
6
 <div>
7
 <p>Enter your first and last name:</p>
8
 <input
9
 type="text"
10
 value={name}
11
 onChange={e => setFirstName(e.target.value)}
12
 />
13
 <input
14
 type="text"
15
 value={name}
16
 onChange={e => setLastName(e.target.value)}
17
 />
18
 </div>
19
 )
20
}
21
​
22
function DisplayName() { 
23
 const [name] = client.hooks.useCloudState("user.name", {});
24
 
25
 //
26
 // name would be an object like:
27
 // {
28
 // first: "john",
29
 // last: "doe"
30
 // }
31
 //
32
​
33
 return (
34
 <div>
35
 <p>Welcome to the app, {name.first} {name.last}</p>
36
 </div>
37
 )
38
}
Copied!
In the above example, using a single hook that gets user.name is more efficient than hooking into user.first.name and user.last.name separately.
defaultValue Parameter Behaviour
Default value is displayed if:
The data is not set for the path
The data is set as either null or undefined for the path
The data is still being loaded from the server.
Error Handling and Loading State
This hook also exposes two parameters for error handling and loading state:
1
import { client } from "./src/utils/cloudState.js";
2
​
3
const path = "user.name"
4
const defaultValue = ""
5
​
6
function HelloWorld() {
7
 const [name, setName, loading, error] = 
8
 client.hooks.useCloudState(path, defaultValue);
9
 
10
 if (loading) {
11
 return (
12
 <p>Loading...</p
13
 );
14
 }
15
 
16
 // error is a Javascript Error object.
17
 if (error) {
18
 return (
19
 <p>An error occurred: {error.message}</p>
20
 );
21
 }
22
​
23
 return (
24
 <div className="HelloWorld">
25
 <input
26
 type="text"
27
 value={name}
28
 onChange={e => setName(e.target.value)}
29
 />
30
 <p>Welcome to my app, {name}!</p>
31
 </div>
32
 )
33
}
Copied!
loading will indicate the loading state of the query.
error will be a javascript Error object or null in case the query is successful.
Internal Behaviour
This hook behaves similar to React.useState, with the possibility of generating a network call when the setter is called. I say possibility, because the CloudState client optimized the number of network calls made to the server internally, if the data is still in the process of being changed.
But for the end-user, the network call is an opaque process. The behaviour observed, is the same as what you'd expect from useState. The local state of the application will be updated immediately, whereas the server state will be updated eventually.
Any cloud query, which may have derived data from the same path will be refreshed to get the new computed query result. For more information on this, see useCloudQuery.
​