Connecting components

Now that you have defined a state describing your application, you probably want to transform that state into a user interface. There are many ways to express this and Overmind supports the most popular libraries and frameworks for doing this transformation, typically called a view layer. You can also implement a custom view layer if you want to.

By installing the view layer of choice you will be able to connect it to your Overmind instance, exposing its state, actions and effects.

React

App.jsx

import * as React from 'react'
import { useOvermind } from '../../overmind'

const App = () => {
  const { state } = useOvermind()

  if (state.isLoading) {
    return <div>Loading app...</div>
  }

  return <h1>My awesome app</h1>
}

export default App

Angular

app.component.ts

import { Component } from '@angular/core';
import { Store } from '../overmind'

@Component({
  selector: 'app-root',
  template: `
<div *track>
  <div *ngIf="state.isLoading">
    Loading app...
  </div>
  <h1 *ngIf="!state.isLoading">
    My awesome app
  </h1>
</div>
  `
})
export class App {
  state = this.store.select()
  constructor(private store: Store) {}
}

Vue

<template>
  <div v-if="state.isLoading">
    Loading app...
  </div>
  <h1 v-else>My awesome app</h1>
</template>

In this example we are accessing the isLoading state. When this component renders and this state is accessed, Overmind will automatically understand that this component is interested in this exact state. It means that whenever the value is changed, this component will render again.

State

When Overmind detects that the App component is interested in our isLoading state, it is not looking at the value itself, it is looking at the path. The component is pointed to state.isLoading which means that when a mutation occurs on that path in the state, the component will render again. Since the value is a boolean value this can only happen when isLoading is replaced or removed. The same goes for strings and numbers as well. We do not say that we mutate a string, boolean or a number. We mutate the object or array that holds those values.

The story is a bit different if the state value is an object or an array. These values can not only be replaced and removed, they can also mutate themselves. An object can have keys added or removed. An array can have items added, removed and even change the order of items. Overmind knows this and will notify components respectively. Let us look at how Overmind treats the following scenarios to get a better understanding.

Arrays

When we just access an array in a component it will re-render if the array itself is replaced, removed or we do a mutation to it. That would mean we push a new item to it, we splice it or sort it.

React

import * as React from 'react'
import { useOvermind } from '../overmind'

const List = () => {
  const { state } = useOvermind()

  return (
    <h1>{state.items}</h1>
  )
}

export default List

Angular

import { Component } from '@angular/core';
import { Store } from '../overmind'

@Component({
  selector: 'app-list',
  template: `
  <h1 *track>{{state.items}}</h1>
  `
})
export class List {
  state = this.store.select()
  constructor(private store: Store) {}
}

Vue

<template>
  <h1>{{ state.items }}</h1>
</template>

But what happens if we iterate the array and access a property on each item?

React

import * as React from 'react'
import { useOvermind } from '../overmind'

const List = () => {
  const { state } = useOvermind()

  return (
    <ul>
      {state.items.map(item => 
        <li key={item.id}>{item.title}</li>
      )}
    </ul>
  )
}

export default App

Angular

import { Component } from '@angular/core';
import { Store } from '../overmind'

@Component({
  selector: 'app-list',
  template: `
  <ul>
    <li *ngFor="let item of state.items;trackby: trackById">
      {{item.title}}
    </li>
  </ul>
  `
})
export class List {
  state = this.store.select()
  constructor(private store: Store) {}
  trackById(index, item) {
    return item.id
  }
}

Vue

<template>
  <ul>
    <li v-for="item in state.items" :key="item.id">
      {{ item.title }}
    </li>
  </ul>
</template>

The benefit now is that the List component will only render when there is a change to the actual list, while each individual Item component will render when its respective title changes.

Objects

Objects are similar to arrays. If you access an object you track if that object is replaced or removed. As with arrays, you can mutate the object itself. When you add, replace or remove a key from the object, it is considered a mutation of the object. It means that if you just access the object, the component will render if any keys are added, replaced or removed.

React

import * as React from 'react'
import { useOvermind } from '../overmind'

const List = () => {
  const { state } = useOvermind()

  return (
    <h1>{state.items}</h1>
  )
}

export default List

Angular

import { Component } from '@angular/core';
import { Store } from '../overmind'

@Component({
  selector: 'app-list',
  template: `
  <h1>{{state.items}}</h1>
  `
})
export class List {
  state = this.store.select()
  constructor(private store: Store) {}
}

Vue

<template>
  <h1>{{ state.items }}</h1>
</template>

And just like an array you can iterate the object keys to pass items to a child component for optimal rendering.

React

Item.jsx

import * as React from 'react'
import { useOvermind } from '../overmind'

const Item = ({ item }) => {
  useOvermind()

  return (
    <li>{item.title}</li>
  )
}

export default Item

Angular

item.component.ts

import { Component Input } from '@angular/core';
import { Item } from '../overmind/state'

@Component({
  selector: 'app-list-item',
  template: `
  <li *track>
    {{item.title}}
  </li>
  `
})
export class List {
  @Input() item: Item;
}

Vue

Item.vue

<template>
  {{ item.title }}
</template>
<script>
export default {
  name: 'Item',
  props: ['item']
}
</script>

React

List.jsx

import * as React from 'react'
import { useOvermind } from '../overmind'
import Item from './Item'

const List = () => {
  const { state } = useOvermind()

  return (
    <ul>
      {Object.keys(state.items).map(key => 
        <Item key={key} item={state.items[key]} />
      )}
    </ul>
  )
}

export default List

Angular

list.component.ts

import { Component Input } from '@angular/core';
import { Item } from '../overmind/state'

@Component({
  selector: 'app-list-item',
  template: `
  <li *track>
    {{item.title}}
  </li>
  `
})
export class List {
  @Input() item: Item;
}

Vue

List.vue

<template>
  <ul>
    <li is="Item" v-for="item in state.items" :item="item" :key="item.id" />
  </ul>
</template>
<script>
import Item from './Item'

export default {
  name: 'List',
  components: {
    Item,
  },
}
</script>

Actions

All the actions defined in the Overmind application are available to connected components.

overmind/actions.js

export const toggleAwesomeApp = ({ state }) =>
  state.isAwesome = !state.isAwesome

React

import * as React from 'react'
import { useOvermind } from '../overmind'

const App = () => {
  const { actions } = useOvermind()

  return (
    <button onClick={actions.toggleAwesomeApp}>
      Toggle awesome
    </button>
  )
}

export default App

Angular

import { Component } from '@angular/core';
import { Store } from '../overmind'

@Component({
  selector: 'app-root',
  template: `
  <button (click)="actions.toggleAwesomeApp()">
    Toggle awesome
  </button>
  `
})
export class App {
  actions = this.store.actions
  constructor(private store: Store) {}
}

Vue

<template>
  <button @click="actions.toggleAwesomeApp()">
    Toggle awesome
  </button>
</template>

If you need to pass multiple values to an action, you should rather use an object instead.

Reactions

Sometimes you want to make something happen inside a component related to a state change. This is typically doing some manual work on the DOM. When you connect a component to Overmind it also gets access to reaction. This function allows you to subscribe to changes in state, mutations as we call them.

This example shows how you can scroll to the top of the page every time you change the current article of the app.

React

import * as React from 'react'
import { useOvermind } from '../../overmind'

const Article = () => {
  const { reaction } = useOvermind()

  React.useEffect(() => reaction(
    (state) => state.currentArticle,
    () => document.querySelector('#app').scrollTop = 0 
  ), [])

  return <article />
}

export default Article

Angular

import { Component } from '@angular/core';
import { Store } from '../overmind'

@Component({
  selector: 'app-root',
  template: `
  <article></article>
  `
})
export class App {
  disposeEffect: () => void
  constructor(private store: Store) {}
  ngOnInit() {
    this.disposeReaction = this.store.reaction(
      (state) => state.currentArticle,
      () => document.querySelector('#app').scrollTop = 0   
    )
  }
  ngOnDestroy() {
    this.disposeReaction()
  }
}

Vue

<template>
  <article></article>
</template>
<script>
export default {
  name: 'Article',
  mounted() {
    this.disposeReaction = this.overmind.reaction(
      (state) => state.currentArticle,
      () => document.querySelector('#app').scrollTop = 0   
    })
  }
  destroyed() {
    this.disposeReaction()
  }
}
</script>

Effects

Any effects you define in your Overmind application are also exposed to the components. They can be found on the property effects. It is encouraged that you keep your logic inside actions, but you might be in a situation where you want some other relationship between components and Overmind. A shared effect is the way to go.