import { useVModel } from "effector-vue/composition";

Returns a writable ref bound to a store: an update of the store reaches the ref, and an edit of the ref is written into the store. It is primarily used for forms with v-model in Vue 3.

Methods

useVModel($store, options?)

Formulae

useVModel($store: Store<State>, options?: UseVModelOptions): Ref<UnwrapRef<State>>;
useVModel<T extends Record<string, Store<any>>>(shape: T, options?: UseVModelOptions): ExtractStore<T>;

Designed for Vue 3.

Arguments

1. $store (Store) or a shape of stores
2. options? (Object)
   • scope? (Scope) to read and to write instead of the scope of the plugin
   • forceScope? (boolean) throw when no scope is resolved instead of falling back to global mode
   • deep? (boolean) watch the value deeply, so that an edit of a nested field reaches the store (default: true)

Returns

A writable Ref with a copy of the state, or an object of such copies for a shape of stores. Editing it writes the whole new value into the store; an update of the store replaces the copy.

Examples

Single Store

import { createStore } from "effector";

export const $user = createStore({
  name: "",
  surname: "",
  skills: ["CSS", "HTML"],
});

<script setup lang="ts">
import { useVModel } from "effector-vue/composition";

import { $user } from "./model";

const user = useVModel($user);
</script>

<template>
  <input type="text" v-model="user.name" />
  <input type="text" v-model="user.surname" />

  <div>
    <input type="checkbox" v-model="user.skills" value="HTML" />
    <input type="checkbox" v-model="user.skills" value="CSS" />
    <input type="checkbox" v-model="user.skills" value="JS" />
  </div>
</template>

Store Shape

import { createStore } from "effector";

export const $name = createStore("");
export const $surname = createStore("");
export const $skills = createStore<string[]>([]);

<script setup lang="ts">
import { useVModel } from "effector-vue/composition";

import { $name, $surname, $skills } from "./model";

const user = useVModel({ name: $name, surname: $surname, skills: $skills });
</script>

<template>
  <input type="text" v-model="user.name" />
  <input type="text" v-model="user.surname" />

  <div>
    <input type="checkbox" v-model="user.skills" value="HTML" />
    <input type="checkbox" v-model="user.skills" value="CSS" />
    <input type="checkbox" v-model="user.skills" value="JS" />
  </div>
</template>

Scope

Under EffectorScopePlugin the form reads and writes the scope of the application, so the input of the user reaches scope.getState($form) and serialize. Without a scope the store itself is written, as before.

import { fork } from "effector";
import { EffectorScopePlugin } from "effector-vue/composition";

const scope = fork();
app.use(EffectorScopePlugin({ scope }));

A call outside of a component, or a call that has to write into another scope, takes the scope as an option:

const form = useVModel($form, { scope });

Shallow binding

By default the copy is watched deeply, so an edit of a nested field writes the whole new value into the store. With deep: false the state of the store is bound as it is and only an assignment of the whole value is written back, which suits a form of primitives or a large state that is mostly read:

const form = useVModel($form, { deep: false });

form.value = { ...form.value, name: "John" };

In this mode the ref holds the state object of the store itself, and an assignment hands that object back without a copy. Writing into a nested field of it changes the state of the store in place, and nothing reads that as an update: the store keeps the same object and no watcher fires. Replace the whole value, the way the example does, or leave deep alone.

Limitations

• The copy of the state is made with structuredClone, so Date, Map, Set, RegExp and typed arrays survive the round trip. If the runtime has no structuredClone, or it throws on some value in the state, a function for one, the whole copy is made with a plain recursive copy instead. That copy keeps functions and dates by reference and turns Map and Set into empty objects. A class instance loses its prototype either way.
• A derived store, the result of map or combine, takes an edit, and the next update of the store it is computed from overwrites it. The composable reports it through console.error; bind the form to that store.
• The second argument used to be a Vue EffectScope. It still works; the options object is the preferred form.