Package Exports

twa-theme-params
twa-theme-params/dist/cjs.js
twa-theme-params/dist/esm.js
twa-theme-params/dist/umd.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (twa-theme-params) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Theme Params

Size

Web Apps theme parameters contain rather important information to follow visual consistency of client application with native one. It provides developer information about which colors are currently used by native application and expects developer to use them.

Motivation

As long as it is important to create applications which look native, developers have to watch for current theme parameters and their changes.

Moreover, user will have better experience in case, when application is loading without "flashes", which usually occur due to on-flight color changes. That's why this library should provide theme information even when application script is still not loaded.

Installation

npm i twa-theme-params

yarn add twa-theme-params

Usage

Preparing application

It is important to display application with colors already known. The only one easy way of getting theme colors before application is displayed, is to get them from current window's location.

To do this, we should create script and place it in head section of document which will extract required parameters. Otherwise, due to some specific problems in platform (issue) , application will "flash".

Thanks to this library, it already has ready to use script. To make everything work, just add script tag with src attribute as follows:

<html>
<head>
    <meta charset="UTF-8">
    <title>Document</title>
    <script src="https://unpkg.com/twa-theme-params/dist/preload-umd.js"></script>
</head>
<body>
</body>

As a result, a set of CSS variables will be ready to use even when body is not loaded. It means, you could display your application with already known colors and use these colors in you CSS files.

Programmatic control

Extracting from JSON

This library contains such useful function as extractThemeFromJson. It accepts JSON object or its string representation and returns TwaThemeParams interface with already prepared and known colors.

import {extractThemeFromJson} from 'twa-theme-params';

// Extract parameter, responsible for application theme parameters.
const tp = new URLSearchParams(window.location.hash.slice(1))
  .get('tgWebAppThemeParams');

// Extract required colors.
console.log(extractThemeFromJson(tp));

// Output:
// {
//   backgroundColor: '#17212b',
//   buttonColor: '#5288c1',
//   buttonTextColor: '#ffffff',
//   hintColor: '#708499',
//   linkColor: '#6ab3f3',
//   secondaryBackgroundColor: '#232e3c',
//   textColor: '#f5f5f5',
// }

ThemeParams

Color properties

Instance of this class contains set of properties, that could return RGB color or null.

These properties are:

backgroundColor
buttonColor
buttonTextColor
hintColor
linkColor
secondaryBackgroundColor
textColor

You are unable to change them directly, because, normally, there should not be any need in this. In case, local (these changes do not affect native app) theme update is required, you should use update function which applies new theme parameters:

import {ThemeParams} from 'twa-theme-params';
import {extractThemeFromJson} from './utils';

const tp = ThemeParams.fromJson({...});
const nextTheme = extractThemeFromJson({...});

tp.update(nextTheme);

If any changes were done, instance will emit change event.

Detecting color scheme

Class is capable of determining if current theme is recognized as dark or light:

import {ThemeParams} from 'twa-theme-params';

const tp = ThemeParams.fromJson({...});

console.log(tp.isDark);

// Output:
// true or false

Events listening

Currently, ThemeParams supports only 1 event change to be listened:

import {ThemeParams, extractThemeFromJson} from 'twa-theme-params';

const tp = ThemeParams.fromJson({...});
const listener = () => {
  console.log('theme params updated', tp);
};

// Add event listener.
tp.on('change', listener);

// Emit this event.
tp.update(extractThemeFromJson({...}));

// Remove event listener.
tp.off('change', listener);

It is worth mentioning, that this event will not be emitted in case, no changes were done.

Contribution

Any contribution is appreciated. Feel free to create new feature requests, bug reports etc.