This project contains a collection of reusable components, developed for the kwantis' software ecosystem.
To import the library inside your project, please follow the instructions below.
With npm
npm install @kwantis-id3/frontend-library
With yarn
yarn add @kwantis-id3/frontend-library
With pnpm
pnpm add @kwantis-id3/frontend-library
Note that the library uses @emotion/styled and @emotion/react as dev dependencies. Installing them in your project may cause conflicts.
The library however offers its own styled utility, that can be used to create styled components.
The library has various components, each one with its own documentation. Please refer to the storybook documentation for more information.
At the moment, the library contains the following components:
-
Accordion
-
Button
-
Select (both single and multi)
-
Slider
-
InputField, can be used as
- Datepicker
- Timepicker
- Datetimepicker
- TextField
- NumberField
- Text alternatives (email, password, url, tel, etc.)
-
Multilevel Dropdown
-
Modal
The following are under development or on our roadmap in no particular order:
- Label
- Checkbox
- Radio
-
Datepicker(supported by InputField) -
Timepicker(supported by InputField) -
Datetimepicker(supported by InputField) - Table
- Tabs
You can find various examples of usage in the projects stories.
The library internally uses the emotion library for styling. By default, the library uses a default theme, that looks like this:
export const defaultThemeColors = {
primary: { main: "#1d4e89", contrastText: "#ffffff" },
secondary: { main: "#00b2ca", contrastText: "#ffffff" },
tertiary: { main: "#7dcfb6", contrastText: "#ffffff" },
statusOk: { main: "#00e200", contrastText: "#ffffff" },
statusWarning: { main: "#efff00", contrastText: "#ffffff" },
statusCritical: { main: "#ff3838", contrastText: "#ffffff" },
statusNeutral: { main: "#7b8089", contrastText: "#ffffff" },
};
You can override the default theme by passing a custom theme to the ThemeContextProvider
component, like this:
import { ThemeContextProvider } from "@kwantis-id3/frontend-library";
const customTheme = {
primary: { main: "#1d4e89", contrastText: "#ffffff" },
secondary: { main: "#00b2ca", contrastText: "#ffffff" },
tertiary: { main: "#7dcfb6", contrastText: "#ffffff" },
statusOk: { main: "#00e200", contrastText: "#ffffff" },
statusWarning: { main: "#efff00", contrastText: "#ffffff" },
statusCritical: { main: "#ff3838", contrastText: "#ffffff" },
statusNeutral: { main: "#7b8089", contrastText: "#ffffff" },
};
const App = () => {
return (
<ThemeContextProvider theme={customTheme}>
<YourApp />
</ThemeContextProvider>
);
};
To add custom properties to the theme, you can extend the ThemeColorsObject
interface in a .d.ts file, like this:
import "@kwantis-id3/frontend-library";
declare module "@kwantis-id3/frontend-library" {
interface ThemeColorsObject {
newColor: Color;
newColor2: Color;
}
}
In case you fetch the theme from an API, there are a couple of things you need to do to avoid complications.
The library uses the ThemeColorsObject
interface to define the theme colors. This interface is used to define the default theme, and to extend it with custom properties, as discussed in the previous section.
If you fetch the theme from an API, it is strongly advised to use a default theme containing the additional keys, and then override it with the fetched one.
Otherwise, the additional keys in the theme may be undefined
, and accessing them before the theme has finished fetching will cause an error.
Here's an example on how to do it, using react query, assuming that the theme has been extended with a newColor
property:
import { ThemeContextProvider, ThemeContextProps } from "@kwantis-id3/frontend-library";
import { useQuery } from "react-query";
const App = () => {
const defaultTheme: ThemeContextProps = {
colors: {
primary: { main: "#cccccc", contrastText: "#cccccc" },
secondary: { main: "#cccccc", contrastText: "#cccccc" },
tertiary: { main: "#cccccc", contrastText: "#cccccc" },
statusOk: { main: "#cccccc", contrastText: "#cccccc" },
statusWarning: { main: "#cccccc", contrastText: "#cccccc" },
statusCritical: { main: "#cccccc", contrastText: "#cccccc" },
statusNeutral: { main: "#cccccc", contrastText: "#cccccc" },
newColor: { main: "#cccccc", contrastText: "#cccccc" },
}
}
const fetchedTheme = useQuery({
queryKey: ["theme"],
queryFn: getColors,
initialData: defaultTheme,
});
return (
<ThemeContextProvider theme={fetchedTheme.data}>
{...}
</ThemeContextProvider>
)
}
If you fetch the theme from an API, you may experience a FOUC (Flash Of Unstyled Content) when the theme is being fetched.
This is because the default theme (either being the one native to the library, or a custom one like in the previous section) is applied before the fetched one is ready, and the two may have some differences (especially if your application needs to be deployed on various instances with different themes).
To avoid this, you have 3 possible solutions:
- Do not render the application until the theme is ready
- Store the theme in the local storage, and use it as the default theme. Please note that this approach will still show the FOUC in the following cases:
- The user has never visited the application before
- The user has cleared the local storage / is using a different browser or device
- The user has visited the application before, but the theme has changed since then
- Use the
initialData
property of theuseQuery
hook to pass a default theme, since useQuery automatically caches the queries data. This approach will still show the FOUC in the following cases:- The user has never visited the application before
- The user has cleared the local storage / is using a different browser or device
- The user has visited the application before, but the theme has changed since then
For case 3, the code remains unchanged from the previous section, so here's an example without react query for case 2:
import { ThemeContextProvider, ThemeContextProps } from "@kwantis-id3/frontend-library";
import React, { useEffect, useState } from "react";
import axios from "axios";
const App = () => {
const defaultTheme: ThemeContextProps = {
colors: {
primary: { main: "#cccccc", contrastText: "#cccccc" },
secondary: { main: "#cccccc", contrastText: "#cccccc" },
tertiary: { main: "#cccccc", contrastText: "#cccccc" },
statusOk: { main: "#cccccc", contrastText: "#cccccc" },
statusWarning: { main: "#cccccc", contrastText: "#cccccc" },
statusCritical: { main: "#cccccc", contrastText: "#cccccc" },
statusNeutral: { main: "#cccccc", contrastText: "#cccccc" },
newColor: { main: "#cccccc", contrastText: "#cccccc" },
}
}
const [theme, setTheme] = React.useState(() => { //initialize state with default or localstorage value
const localTheme = localStorage.getItem("myStoredTheme");
if (localTheme) {
return JSON.parse(localTheme) as ThemeContextProps;
}
return defaultTheme;
});
useEffect(() => {
axios.get<ThemeContextProps>("theme")
.then((response) => {
setTheme(response.data);
localStorage.setItem("myStoredTheme", JSON.stringify(response.data));
})
.catch ((error) => {
console.log(error);
})
}, []);
return (
<ThemeContextProvider theme={theme}>
{...}
</ThemeContextProvider>
)
}
The library exports a useThemeContext
hook, that can be used to access the theme object from any component,
exposing a ThemeProperties
object.
import { useThemeContext } from "@kwantis-id3/frontend-library";
const MyComponent = () => {
const theme = useThemeContext();
useEffect(() => {
console.log(theme);
}, [theme]);
return <div>...</div>;
};
Through the ThemeProperties
object, you can access the theme colors either directly, or through the getColor(color: string) => Color
property,
that will return a valid Color based on the string parameter that it’s passed to it.
const theme = useThemeContext();
const primaryColor = theme.colors.primary.main;
// or
const primaryColor = theme.getColor("primary");
Basically, the property getColor
can be used to:
- Access the theme colors, in 2 ways:
- Access the color directly, if the passed string is a valid key of the
ThemeColorsObject
interface. This is the same as accessing the color directly from thecolors
property, giving you access to the possible custom properties that you may have added to the theme. - Access the color through a path, if the passed string is a valid path of the
ThemeColorsObject
interface. This returns aColor
object, that has only themain
andcontrastText
properties, wheremain
is the color that you are accessing, andcontrastText
is generated automatically to grant the best readability possible.
- Access the color directly, if the passed string is a valid key of the
- Generate a valid
Color
object, if the passed string is a valid hex code or css color function
In the latter case, the contrastText property will automatically be generated to grant the best readability possible.
If the passed string is not a valid color, the function will default to the primary color of the theme.
const tertiartyColor = theme.getColor("tertiary");
console.log(tertiaryColor); // { main: "#7dcfb6", contrastText: "#ffffff" }
const tertiartyTextColor = theme.getColor("tertiary.contrastText");
console.log(tertiaryTextColor); // { main: "#ffffff", contrastText: "#000000"}
const fuchsia = theme.getColor("fuchsia");
console.log(fuchsia); // { main: "fuchsia", contrastText: "#000000" }
const rgba = theme.getColor("rgba(130, 146, 9, 0.5)");
console.log(rgba); // { main: "rgba(130, 146, 9, 0.4)", contrastText: "#000000" }
const notValid= theme.getColor("whatever123");
console.log(notValid); // { main: "#1d4e89", contrastText: "#ffffff" }
Each component that has a color prop, accepts a string. The string can be a color name, a color path, a hex code, or a css color function.
// Color name
<Button color="primary" />
// Color path
<Button color="primary.contrastText" />
// Hex code
<Button color="#1d4e89" />
// Css color function
<Button color="rgb(29, 78, 137)" />
The library exports a styled
utility, that can be used to create styled components.
It works exactly like the styled
utility from the @emotion/styled
library, but it automatically passes the theme to the component.
import { styled } from "@kwantis-id3/frontend-library";
const StyledButton = styled.button`
background-color: ${(props) => props.theme.colors.primary.main};
color: ${(props) => props.theme.colors.primary.contrastText};
`;
const MyComponent = () => {
return <StyledButton>Click me!</StyledButton>;
};
It also automatically updated if the Theme interface is extended, so you don’t have to worry about updating it manually.
If you want to create a styled component with props, you can do so using the transientOptions
utility, like this:
import { styled, transientOptions } from "@kwantis-id3/frontend-library";
export const StyledDiv = styled("div", transientOptions)<{
$bgColor: string;
}>`
background: ${(props) => props.$bgColor};
`;
const MyComponent = () => {
return <StyledDiv $bgColor="red">I'm red!</StyledDiv>;
};
It's important that the props defined this way are prefixed with a $
sign, to avoid conflicts with the native HTML props.