karet

≡ Karet ·

Karet is a library that allows you to embed Kefir properties into React Virtual DOM. Embedding observable properties into VDOM has the following benefits:

• It allows you to use only functional components, because you can then use observables for managing state and component lifetime, leading to more concise code.
• It helps you to use React in an algorithmically efficient way:
  • The body of a functional component is evaluated only once each time the component is mounted.
  • Only elements that contain embedded properties are rerendered when changes are pushed through observables. An update to a deeply nested VDOM element can be an O(1) operation.

Using Karet couldn't be simpler. Usually you just import * as React from 'karet' and you are good to go.

≡ Contents

• Tutorial
• Reference
  • Fragment
  • karet-lift attribute
  • fromClass(Component)

≡ Tutorial

To use Karet, you simply import it as React:

import * as React from "karet"

and you can then write React components:

const App = () => (
  <div>
    <h1>What is the date and time</h1>
    {Kefir.interval(1000)
      .toProperty(() => {})
      .map(() => new Date().toString())}
  </div>
)

with VDOM that can have embedded Kefir properties. This works because Karet exports an enhanced version of createElement.

Here is a live example in CodeSandbox.

NOTE: Karet does not pass through all named React exports. Only createElement and Fragment are exported, which is all that is needed for basic use of VDOM or the Babel JSX transform.

NOTE: The result, like the date and time dispplay above, is just a React component. If you export it, you can use it just like any other React component and even in modules that do not import karet.

≡ Reference

≡ Fragment

In addition to createElement, Karet exports React's Fragment component and lifts fragments implicitly.

≡ karet-lift attribute

Karet only lifts built-in HTML elements and fragments implicitly. The karet-lift attribute on a non-primitive element instructs Karet to lift the element.

For example, you could write:

import Select from 'react-select'
import * as React from "karet"

// ...

const ReactSelect1 = ({value}) => (
  <Select
    karet-lift
    name="form-field-name"
    value={value}
    options={options}
    onChange={o => value.set(o && o.value)}
  />
)

to be able to use Select from React Select with embedded Kefir Atoms.

Here is a live example in CodeSandbox.

≡ fromClass(Component)

Karet only lifts built-in HTML elements and fragments implicitly. fromClass allows one to create lifted version of a given React component.

For example, you could write:

import Select from 'react-select'
import * as React from "karet"

const SelectLifted = React.fromClassdate and time dispplay

const ReactSelect2 = ({value}) => (
  <SelectLifted
    name="form-field-name"
    value={value}
    options={options}
    onChange={o => value.set(o && o.value)}
  />
)

to be able to use Select from React Select with embedded Kefir Atoms.

Here is a live example in CodeSandbox.

Changelog

3.0.0

Only Kefir properties, in other words, objects that inherit Kefir.Property, are lifted. Kefir.Stream and Kefir.Observable objects are not lifted and will result in errors.

Dropped previously obsoleted fromKefir combinator.

$$ref is no longer required due to using React.forwardRef in fromClass.