123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210
---title: 'Getting Started'description: 'Get started with valtio.'---
import logo from './logo.svg'
<img src={logo} alt="valtio" /># Valtio
### Proxy state made simple.
The Valtio api is minimal, flexible, unopinionated and a touch magical. Valtio's proxy turns the object you pass it into a self-aware proxy, allowing fine-grained subscription and creativity in making state updates. In React, Valtio shines at render optimization. It is compatible with Suspense and React 18. Valtio is also a viable option in vanilla javascript applications.
#### Installation
```bashnpm i valtio```
#### The to-do app example
#### 1. proxy
Let's learn Valtio by coding a simple to-do app in React and Typescript. We'll start by creating some state using [`proxy`](/docs/basic/proxy).
```tsimport { proxy, useSnapshot } from 'valtio'
type Status = 'pending' | 'completed'type Filter = Status | 'all'type Todo = {  description: string  status: Status  id: number}
export const store = proxy<{ filter: Filter; todos: Todo[] }>({  filter: 'all',  todos: [],})```
#### 2. useSnapshot
To access the data in this store, we'll use [`useSnapshot`](/docs/basic/useSnapshot). The Todos component will rerender when the "todos" or "filter" propeties are updated. Any other data we add to the proxy will be ignored.
```tsxconst Todos = () => {  const snap = useSnapshot(store)  return (    <ul>      {snap.todos        .filter(({ status }) => status === snap.filter || snap.filter === 'all')        .map(({ description, status, id }) => {          return (            <li key={id}>              <span                data-status={status}                className="description"                {description}              </span>              <button className="remove">                x              </button>            </li>          )        })}    </ul>  )}```
#### 3. actions
Finally, we need to create, update, and delete our todos. To do so, we simply mutate properties on the store we created, not the snap. Commonly, these mutations are wrapped up in functions called actions.
```tsconst addTodo = (description: string) => {  store.todos.push({    description,    status: 'pending',    id: Date.now(),  })}
const removeTodo = (index: number) => {  store.todos.splice(index, 1)}
const toggleDone = (index: number, currentStatus: Status) => {  const nextStatus = currentStatus === 'pending' ? 'completed' : 'pending'  store.todos[index].status = nextStatus}
const setFilter = (filter: Filter) => {  store.filter = filter}```
Finally, we wire up these actions to our inputs and buttons - check the demo below for the full code.
```tsx<button className="remove" onClick={() => removeTodo(index)}>  x</button>```
## Codesandbox demo
https://codesandbox.io/s/valtio-to-do-list-hm5kwz
#### Mutating state outside of components
In our first to-do app, Valtio enabled mutations without worrying about performance or "breaking" React. `useSnapshot` turned these mutations into immutable snapshots and optimized renders. But we could have easily used React's own state handling. Let's add a bit of complexity to our to-do app to see what else Valtio offers.
We will add a "timeLeft" property to a todo. Now each todo will tick down to zero and become "overdue" if not completed in time.
```tstype Todo = {  description: string  status: Status  id: number  timeLeft: number}```
Among other changes, we will add a Countdown component to display the ticking time for each todo. We are using an advanced technique of passing a nested proxy object to [`useSnapshot`](/docs/basic/useSnapshot). Alternatively, make this a dumb component by passing the todo's "timeLeft" as a prop.
```tsximport { useSnapshot } from 'valtio'import { formatTimeDelta, calcTimeDelta } from './utils'import { store } from './App'
export const Countdown = ({ index }: { index: number }) => {  const snap = useSnapshot(store.todos[index])  const delta = calcTimeDelta(snap.timeLeft)  const { days, hours, minutes, seconds } = formatTimeDelta(delta)  return (    <span className="countdown-time">      {delta.total < 0 ? '-' : ''}      {days}      {days ? ':' : ''}      {hours}:{minutes}:{seconds}    </span>  )}```
#### Mutate in module scope
Instead of managing multiple timers inside of a React component, let's move these updates outside of React altogether by defining a recursive `countdown` function in module scope which will mutate the todos.
```tsxconst countdown = (index: number) => {  const todo = store.todos[index]  // user removed todo case  if (!todo) return  // todo done of overdue case  if (todo.status !== 'pending') {    return  }  // time over  if (todo.timeLeft < 1000) {    todo.timeLeft = 0    todo.status = 'overdue'    return  }  setTimeout(() => {    todo.timeLeft -= 1000    countdown(index)  }, 1000)}```
We can start the recursive countdown from an enhanced `addTodo` action.
```tsxconst addTodo = (e: React.SyntheticEvent, reset: VoidFunction) => {  e.preventDefault()  const target = e.target as typeof e.target & {    deadline: { value: Date }    description: { value: string }  }  const deadline = target.deadline.value  const description = target.description.value  const now = Date.now()  store.todos.push({    description,    status: 'pending',    id: now,    timeLeft: new Date(deadline).getTime() - now,  })  // clear the form  reset()  countdown(store.todos.length - 1)}```
Please see the rest of the changes in the demo below.
#### Subscribe in module scope
Being able to mutate state outside of components is a huge benefit. We can also [`subscribe`](/docs/basic/subscribe) to state changes in module scope. We will leave it to you to try this out. You might, for instance, persist your todos to local storage as in [this example](https://github.com/pmndrs/valtio/wiki/How-to-persist-states#persist-with-localstorage).
## Codesandbox demo
https://codesandbox.io/s/valtio-countdown-to-do-list-xkgmri