README.md

zustand-lit

A zustand adapter for lit

Zustand is a lightweight state manager for javascript applications

Install

npm install zustand zustand-lit

Version 2.0.0 breaking changes!

1. Removed observe decorator
2. Removed connect mixin function
3. Added watch and watchWithSelector decorators

Motivation:

The connect and observe adapters update the component whenever the state changes. On top of that unnecessary renders are happened. To avoid this problems the new watchWithSelector API was created.

Usage

You have to use createStore factory function from zustand/vanilla package.

• Choose @watch if you have no many data and/or for static objects (like config, user, etc.)
• Choose @watchWithSelector for performance control
• Choose Context API to create 3d party library

@watch and @watchWithSelector decorators

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { createStore } from 'zustand/vanilla';
import { watch } from 'zustand-lit';


interface BearState {
  bears: number;
  addBear: () => void;
}

const BearStore = createStore<BearState>(set => ({
  bears: 0,
  addBear: () => set(state => ({ bears: state.bears + 1 })),
}));

@customElement('bears')
class BearsElement extends LitElement {
  @watch(BearStore) state?: BearState;

  render() {
    return html`
      <p>${this.state?.bears}</p>
      <button @click=${this.state?.addBear}>
        Add bear
      </button>
    `;
  }
}

To control renders you are able to use watchWithSelector decorator

import { watchWithSelector } from 'zustand-lit';


interface ZooState {
  bears: number;
  cows: number;
  monkeys: number;
  snakes: number;
}

const selectBears = (state: ZooState) => state.bears;

@customElement('bears')
class BearsElement extends LitElement {
  @watchWithSelector({ store: ZooStore, selector: selectBears })
  bears?: number;
}

watchWithSelector options

Parameter	Mandatory	Default	Description
store	Yes	-	Store object created by createStore
selector	Yes	-	A state extractor
equalityFn	No	Object.is	A function that lets you skip re-renders

Context API

Before using context api you have to install @lit/context package.
For more information take a look at the docs

Usage

• @withZustandProvider to create provider component
• @consume from @lit/context to read store value
• @consumeWithSelector for performance control
• updateState(context, value) to update state

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { consume, createContext } from '@lit/context';
import { withZustandProvider, updateState } from 'zustand-lit/context';


interface BearState {
  bears: number;
}

const initialState: BearState = {
  bears: 0
};

const BearContext = createContext<BearState>('bear-context');

@customElement('bears-provider')
@withZustandProvider({ context: BearContext, initialState }) 
class BearsProvider extends LitElement {
  render() {
    return html`<bears-consumer></bears-consumer>`;
  }
}

@customElement('bears-consumer')
class BearsConsumer extends LitElement {
  @consume({ context: BearContext, subscribe: true })
  state?: BearsState;

  addBears() {
    const current = this.state?.bears ?? 0;
    updateState(BearContext, { bears: current + 1 });
  }

  render() {
    return html`
      <p>${this.state?.bears}</p>
      <button @click=${this.addBears}>
        Add bear
      </button>
    `;
  }
}

To control renders you are able to use consumeWithSelector decorator

import { consumeWithSelector } from 'zustand-lit/context';


interface ZooState {
  bears: number;
  cows: number;
  monkeys: number;
  snakes: number;
}

const selector = (state: ZooState): number => state.bears;

@customElement('bears-consumer')
class BearsConsumer extends LitElement {
  @consumeWithSelector({ context: BearContext, selector })
  bears?: number;
}

consumeWithSelector options

Parameter	Mandatory	Default	Description
context	Yes	-	Context object created by createContext
selector	Yes	-	A state extractor
equalityFn	No	Object.is	A function that lets you skip re-renders

License

This project is licensed under the MIT License - see the LICENSE file for details