Events

Although effector has three main concepts — events, stores, and effects — it is events that can be called the foundation for how your application works. The entire frontend is built atop an event-driven model, and you have most likely already worked with events in JavaScript, for example via addEventListener or React handlers like onClick. They are all events we can subscribe to, and effector lets us create our own event with createEvent and subscribe to it:

let counter = 10;

document.addEventListener("click", () => {
  counter = 13;
});

import { createEvent, createStore, sample } from "effector";

const $counter = createStore(10);

const click = createEvent();

sample({
  clock: click,
  fn: () => 13,
  target: $counter,
});

Why we need events

All effector code is built on top of events. For example, if you pass a store to the clock argument of sample, that sample will be triggered whenever the updates event of the store fires:

// this code is equivalent to the example on the right
import { createStore, sample } from "effector";

const $someStore = createStore();
sample({
  clock: $someStore,
  // ...
});

// this code is equivalent to the example on the left
import { createStore, sample } from "effector";

const $someStore = createStore();
sample({
  clock: $someStore.updates,
  // ...
});

An event by itself simply states the fact that something has happened: a button click, data refresh, notification display, and so on. Events pass information along and notify their subscribers that they have been triggered.

To make it easier to reason about your code, treat everything the user can interact with and the inner parts of your business logic as events. Besides UI-oriented events like buttonClicked or inputChanged, you can also have events tied to data updates valueUpdated or exceptional situations errorOccurred.

For example, effects have built-in events done and fail that run when an effect finishes successfully or throws an error. Stores have the updates event that is triggered whenever the store changes.

Events also help you keep the code loosely coupled, which simplifies maintenance and testing.

How to use events

You can create events with createEvent and subscribe to them with sample:

import { sample, createEvent } from "effector";

const event = createEvent();

sample({
  clock: event,
  // ...
});

With events you can update stores, trigger effects, or fire other events:

import { sample, createStore, createEvent } from "effector";

const $clicksCount = createStore(0);

const userClicked = createEvent<void>();

// update the counter store
sample({
  clock: userClicked,
  source: $clicksCount,
  fn: (clicksCount) => clicksCount + 1,
  target: $clicksCount,
});

userClicked();

import { createEvent, createEffect, sample } from "effector";

const startFetch = createEvent<string>();
const fetchFx = createEffect((url: string) => {
  // ...
});

// trigger an effect
sample({
  clock: startFetch,
  target: fetchFx,
});

startFetch("/fake-api/users");

An important characteristic of events is that they can accept only one argument; additional arguments are ignored. Use an object if you need to pass multiple values:

const event = createEvent<{ a: number; b: string }>();

event({
  a: 1,
  b: "string",
});

Event calling

You can trigger an event in two ways: imperatively or declaratively.

The imperative approach is a familiar one, where you call an event as a function (event()). This is how you will typically fire events from the UI by passing a handler to onClick, onChange, and so on:

import { createEvent } from "effector";
// you can use any framework and its integration package
import { useUnit } from "effector-react";

const clickHappened = createEvent<void>();

// view.tsx
const Component = () => {
  const click = useUnit(clickHappened);

  return (
    <div>
      <button onClick={() => click()}>click</button>
    </div>
  );
};

A declarative call happens when you connect one event to another with sample and the target argument. The event passed into target will run whenever the clock event fires:

import { createEvent, sample } from "effector";

const firstTriggered = createEvent<void>();
const secondTriggered = createEvent<void>();

sample({
  clock: firstTriggered,
  target: secondTriggered,
});

Related API and docs

• API
  • Event API — description of events, their methods, and properties
  • createEvent — create a new event
  • sample — the key operator for connecting units
  • Store API — description of stores, their methods, and properties
• Articles
  • How to think in the effector paradigm and why events matter
  • Typing events and other units
  • How to glue units together with sample and createAction