Version: 1.2.0

Theming Support

Overview

Selecting a website theme can be overwhelming. The theme is the overall look, feel, and style. This includes things like the color scheme, layout, and style elements. In essence, application themes are a direct representation of brands and have a direct impact on users' experience. In modern web applications, users are heavily attracted to one feature which is a dark theme. This library provides built-in support for the theme. Users can change themes for the entire UI through a single interface, adjusting all the colors to the theme you have selected.

Why We Need a Theme?

Dark mode in multiple applications became really popular in 2019. Reasons being it looks more attractive and is more readable in lower light. The majority of users prefer to use applications that are less strenuous to their eyes and require less pressure on their sight. The main issue with the theme in web applications is, they are difficult to implement in terms of consistency, maintainability, and reusability. Ideally, we would like to implement a single interface to control all theme-related constraints like layouts, styles, and colors, which K2 achieves.
As we discussed before, the theme is a direct representation of a company's brand and it also controls colors, layout, and styles.
For example, if you decide to implement two themes for your application. You will only need to provide details (colors, styles, and layout) about individual themes through a single interface. The given detail will be accessible to each individual react component and you can use any of them according to your requirements. It can be easily possible with styled-components.

Quick Start

K2 is a front-end library with rich visualizations and features. A good starting point of every application is a theme, so here we are going to implement basic themes step by step with an example. This will get you acquainted with K2, all its features and possibilities.

Basic

First of all, we define an interface that controls the theme. Here we have two theme modes i.e light & dark. This interface can be defined in separate files for readability & separation of concern. We put the following code in theme-interface.ts. The code snippet is the basic example of an interface.

export const themeInterface = {
  light: {
    backgroundColors: {
      card: "#fff",
    },
    borderColors: {
      card: "#e6e6e6",
    },
    boxShadowColors: {
      card: "rgba(178, 178, 178, 0.29)",
    },
  },
  dark: {
    backgroundColors: {
      card: "#0c1427",
    },
    borderColors: {
      card: "#1b284b",
    },
    boxShadowColors: {
      card: "transparent",
    },
  },
  card: {
    borderRadius: "8px",
    bodyPadding: "20px",
    headerPadding: "10px 20px",
    hasBorder: true,
    hasBoxShadow: false,
    hasHeaderBorder: false,
  },
  gridLayout: {
    layout: [
      { widthUnits: 1, heightUnits: 2 },
      { widthUnits: 1, heightUnits: 2 },
      { widthUnits: 1, heightUnits: 2 },
      { widthUnits: 4, heightUnits: 2 },
    ],
    rowHeight: 488,
    noOfCols: 4,
    gridGap: [20, 20],
  },
};

Then import ThemeProvider in another file, it can be app.tsx or different. It is a wrapper that wraps all the application elements which will be affected by the theme.

import { Theme } from "@k2/utils";
const { ThemeProvider } = Theme;

The final step to make the theme properties accessible is to wrap your main/root element in ThemeProvider. We will use the theme on Card component so we will import it from another package which is @k2/ui

import React from "react";
import { Theme } from "@k2/utils";
import { Card } from "@k2/ui";

import { themeInterface } from "./theme-interface";

export function YourDashboard(props) {
  return (
    <Theme.ThemeProvider theme={themeInterface}>
      <Card title="card 1"></Card>
    </Theme.ThemeProvider>
  );
}

Toggle Theme

K2 provides built-in toggle theme functionality also you can develop a custom component for toggling a theme.

import React from "react";
import { Theme } from "@k2/utils";
import { Card, ToggleTheme } from "@k2/ui";

import { themeInterface } from "./theme-interface";

export function YourDashboard(props) {
  return (
    <Theme.ThemeProvider theme={themeInterface}>
      <ToggleTheme />
      <Card title="card 1"></Card>
    </Theme.ThemeProvider>
  );
}

How it Works?

What ThemeProvider does? It selects the theme object based on the selected theme mode. Then injects all properties in children along with mode: string & toggleMode: mode => void. We have a custom component "Button."

// file-name: button.tsx
import React from "react";
import styled from "styled-components";
import { Theme } from "@k2/utils";
import { ToggleTheme } from "@k2/ui";

import { themeInterface } from "./theme-interface";

const ButtonStyled = styled.button`
  background: ${props => props.theme.backgroundColors.card};
`;

function Button() {
  return <ButtonStyled>Click</ButtonStyled>;
}

export function YourDashboard() {
  return (
    <Theme.ThemeProvider theme={themeInterface}>
      <ToggleTheme />
      <Button />
    </Theme.ThemeProvider>
  );
}

Theme Interface

The single point to control your theme is the theme interface. It is a JavaScript object which contains theme objects as well as common object. Light or dark mode contains properties related to the theme which are affected by the theme change. The common object contains properties which are common in every theme e.g font-size, line-height, etc. Following is the props table for the theme interface.

Property	Type	Required	Default value
light	ThemeParameterProps	No	`undefined`
dark	ThemeParameterProps	No	`undefined`
common	CommonProps	No	`undefined`
card	CardProps	No	`undefined`
gridLayout	GridLayoutProps	No	`undefined`

ThemeParameterProps

Property	Type	Required	Default value
textColors	TextColorsProps	No	`undefined`
borderColors	BorderColorsProps	No	`undefined`
boxShadowColors	BoxShadowColorsProps	No	`undefined`
backgroundColors	BackgroundColorsProps	No	`undefined`
pieColors	ColorsProps	No	`undefined`
columnColors	ColorsProps	No	`undefined`
barColors	ColorsProps	No	`undefined`
lineColors	ColorsProps	No	`undefined`
areaColors	ColorsProps	No	`undefined`
sankeyColors	SankeyColors	No	`undefined`
bubbleColors	string []	No	`undefined`

TextColorsProps

Property	Type	Required	Default value
info	string	No	`undefined`
error	string	No	`undefined`
success	string	No	`undefined`
warning	string	No	`undefined`
normal	string	No	`undefined`
heading	string	No	`undefined`
axis	string	No	`undefined`
tooltip	string	No	`undefined`

BorderColorsProps

Property	Type	Required	Default value
info	string	No	`undefined`
error	string	No	`undefined`
success	string	No	`undefined`
warning	string	No	`undefined`
card	string	No	`undefined`
bar	string	No	`undefined`

BoxShadowColorsProps

Property	Type	Required	Default value
card	string	No	`undefined`
tooltip	string	No	`undefined`

BackgroundColorsProps

Property	Type	Required	Default value
info	string	No	`undefined`
error	string	No	`undefined`
success	string	No	`undefined`
warning	string	No	`undefined`
card	string	No	`undefined`
main	string	No	`undefined`
tooltip	string	No	`undefined`
primary	string	No	`undefined`
secondary	string	No	`undefined`
axis	string	No	`undefined`

SankeyColors

Property	Type	Required	Default value
nodeColorScheme	string[]	No	`undefined`
linkColor	string	No	`undefined`

ColorsProps

type GradientColors = {
  name: string;
  startingColor: string;
  endingColor: string;
  startingColorStopOpacity?: number;
  endingColorStopOpacity?: number;
  x1?: string;
  x2?: string;
  y1?: string;
  y2?: string;
}[];

type ColorsProps = string[] | GradientColors;

CommonProps

Property	Type	Required	Default value
fontSizes	FontSizesProps	No	`undefined`
borderWidth	string	No	`undefined`
textFontFamily	string	No	`undefined`
numberFontFamily	string	No	`undefined`
letterSpacing	string	No	`undefined`

FontSizesProps

type FontSizesProps = {
  small: string,
  normal: string,
  heading: string,
  large: string,
  xLarge: string,
};

CardProps

Property	Type	Required	Default value
borderRadius	string	No	`undefined`
bodyPadding	string	No	`undefined`
headerPadding	string	No	`undefined`
hasBorder	boolean	No	`undefined`
hasBoxShadow	boolean	No	`undefined`
hasHeaderBorder	boolean	No	`undefined`

GridLayoutProps

Property	Type	Required	Default value
layout	{ heightUnits?: number \| BreakPoints ; widthUnits?: number \| BreakPoints; }[]	No	`undefined`
breakpoints	BreakPoints	No	`undefined`
rowHeight	number	No	`undefined`
noOfCols	number \| BreakPoints	No	`undefined`
rowOffsets	number[]	No	`undefined`
gridGap	GridGap	No	`undefined`

Precedence

Mostly theme properties can be used on an individual level. So we have done some prioritization.

Component props > Custom theme > Default theme > Default props

Name	Precedence	Description
Component props	1st	Properties of a K2 component.
Custom theme	2nd	Custom theme defined by user.
Default theme	3rd	Default theme of K2.
Default props	last	Default properties of a K2 component.

Why We Need a Theme?#

Quick Start#

Basic#

Toggle Theme#

How it Works?#

Theme Interface#

ThemeParameterProps#

TextColorsProps#

BorderColorsProps#

BoxShadowColorsProps#

BackgroundColorsProps#

SankeyColors#

ColorsProps#

CommonProps#

FontSizesProps#

CardProps#

GridLayoutProps#

Precedence#