divkit

import {render} from '@divkitframework/divkit/server';

const html = render({
    id: 'smth',
    json: {
        card: {},
        templates: {}
    },
    onError(details) {
        console.error(details.error);
    }
});

Then use /client-hydratable on client to hydrate server-side html::

import {render} from '@divkitframework/divkit/client-hydratable';

render({
    id: 'smth',
    target: document.querySelector('#root'),
    hydrate: true,
    json: {
        card: {},
        templates: {}
    },
    onError(details) {
        console.error(details.error);
    }
});

Client-only rendering

For the client-only usage there is /client module. The size of this module is slightly smaller than /client-hydratable.

import {render} from '@divkitframework/divkit/client';

render({
    id: 'smth',
    target: document.querySelector('#root'),
    json: {
        card: {},
        templates: {}
    },
    onError(details) {
        console.error(details.error);
    }
});

Are you want to use ES module or CommonJS module?

The package contains both of them.

Node.js will automatically use the appropriate version.

Webpack will use ES modules version.

For the direct CommonJS usage, this files can be used:

dist/client.js
dist/client-hydratable.js
dist/server.js

ES modules files:

dist/esm/client.mjs
dist/esm/client-hydratable.mjs
dist/esm/server.mjs

ES modules can be used in the browser directly without any build:

<script type="module">
    import {render} from './node_modules/@divkitframework/divkit/dist/esm/client.mjs';

    render({
        id: 'smth',
        target: document.querySelector('#root'),
        json: {
            card: {},
            templates: {}
        },
        onError(details) {
            console.error(details.error);
        }
    });
</script>

Use in the browser via global variables without build:

<script src="./node_modules/@divkitframework/divkit/dist/browser/client.js"></script>
<script>
    window.Ya.Divkit.render({
        id: 'smth',
        target: document.querySelector('#root'),
        json: {
            card: {},
            templates: {}
        },
        onError(details) {
            console.error(details.error);
        }
    });
</script>

Usage with React

There is a separate package for that.

React component package

TypeScript and types

All modules have typescript definitions (client, client-hydratable and server), so typescript will load them at any use.

Browser/Node.js support

Browser support

chrome >= 58
safari >= 11
firefox >= 67

Node.js

Node.js >= 8

API: render

All 3 exported modules have an exported function render. This function works in a similar way on client and server.

/client and /client-hydratable requires option target - an HTML-element that is used to render json.

Instead, /server module will return an HTML string.

id

String, required.

Means the unique block identifier. Used to generate ids and classes. There should not be 2 blocks with the same id on the page.

json

Object, required.

Divjson itself.

target

/client and /client-hydratable

HTML-element, required.

hydrate

/client-hydratable

Boolean, optional.

It must be true, if the current render must hydrate html in target.

onError

Function, optional.

Callback for errors and warnings for manual processing.

function onError(detauls: {
    error: Error & {
        level: 'error' | 'warn';
        additional: Record<string, unknown>;
    };
}) {
    console.log(error.level, error.additional, error.message);
}

onStat

/client and /client-hydratable

Function, optional.

Used for logging clicks (for elements with action) and visibility logging (for elements with visibility_action).

function onStat(details: {
    type: 'click' | 'visible';
    action: Action | VisibilityAction;
}) {
}

onCustomAction

/client and /client-hydratable

Function, optional.

Callback for a component with an action that contains non-standard protocols.

function onCustomAction(action: Action): void {
}

platform

desktop | touch | auto

The default value is auto. Tweaks for mouse or touch events.

mix

String, optional.

An additional class added to the root element.

customization

Object, optional.

Currently supported properties:

galleryLeftClass — left scroll button class on desktop
galleryRightClass — right scroll button class on desktop

builtinProtocols

String array, optional. Default value is ['http', 'https', 'tel', 'mailto', 'intent']

Components with an action containing a protocol from the list will be rendered as <a>, and clicking on them will be processed by the browser. Protocols outside the list will cause the element to be rendered as a button-like, and clicking on them causes an 'onCustomAction'.

theme (EXPERIMENTAL)

system | light | dark

The default value is system. Affects variables in palette.

Palette support (EXPERIMENTAL)

Divjson along with the card and templates can contain a palette property with colors for light and dark themes:

{
    "card": {
        "states": [
            {
                "div": {
                    "type": "text",
                    "text": "Hello palette",
                    "text_color": "@{text}",
                    "background": [{
                        "type": "solid",
                        "color": "@{bg}"
                    }]
                },
                "state_id": 0
            }
        ],
        "log_id": "test"
    },
    "templates": {},
    "palette": {
        "dark": [
            {
                "name": "bg",
                "color": "#000"
            },
            {
                "name": "text",
                "color": "#fff"
            }
        ],
        "light": [
            {
                "name": "bg",
                "color": "#fff"
            },
            {
                "name": "text",
                "color": "#000"
            }
        ]
    }
}

The theme can be changed at any time:

instance.setTheme('dark');

API: other

Variables

import {createVariable, createGlobalVariablesController, render} from '@divkit/divkit';

// Custom variable outside of DivJson
const variable = createVariable('name', 'string', 'val');

variable.subscribe(newVal => {
    console.log(newVal);
});

// Custom scope for variables
const controller = createGlobalVariablesController();

controller.setVariable(variable);

render(({
    id: 'smth',
    target: document.querySelector('#root'),
    json: {},
    globalVariablesController: controller
});

Documentation. Medium tutorial. Habr tutorial.

Telegram: News | English-speaking chat | Чат на русском.

Twitter