# @bolttech/frontend-foundations

> [![N|Solid](https://www.bolttech.co.th/blog/wp-content/uploads/2020/10/logo.png)](https://bolttech.io)

Latest version **0.12.3** (published 2026-06-08) · 0 weekly downloads

## Install

```sh
npm install @bolttech/frontend-foundations
pnpm add @bolttech/frontend-foundations
yarn add @bolttech/frontend-foundations
bun add @bolttech/frontend-foundations
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.12.3 |
| Published | 2026-06-08 |
| First published | 2023-11-06 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 74.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | andsfranbolt, danielkhalebbatista, pauloazevedo-ed, bruno.gomes, plinio.altoe, joaoteixeira20, esteve-cabrera, jabolttech, lucasvpaiva, herberts.fortuna, matheus.maciel.bolttech, silas.silva.bolttech |

## Links

- npm: https://www.npmjs.com/package/@bolttech/frontend-foundations
- npm.io page: https://npm.io/package/@bolttech/frontend-foundations

## Dependencies (6)

- [react](https://npm.io/package/react.md) 19.1.2
- [sanitize-html](https://npm.io/package/sanitize-html.md) ^2.13.0
- [styled-components](https://npm.io/package/styled-components.md) 6.1.1
- [@bolttech/ui-utils](https://npm.io/package/@bolttech/ui-utils.md) 0.6.7
- [@testing-library/react](https://npm.io/package/@testing-library/react.md) latest
- [@bolttech/default-theme](https://npm.io/package/@bolttech/default-theme.md) 0.18.2

## Recent versions

- 0.12.3 (latest) — 2026-06-08
- 0.12.2 — 2026-04-14
- 0.12.0 — 2026-04-08
- 0.11.0 — 2026-02-10
- 0.10.2 — 2026-02-10
- 0.10.1 — 2025-09-23
- 0.10.0 — 2024-11-12
- 0.9.5-beta.0 — 2024-11-08
- 0.9.4 — 2024-09-12
- 0.9.3 — 2024-09-05
- 0.9.2 — 2024-09-05
- 0.9.1 — 2024-09-04
- 0.9.0 — 2024-09-04
- 0.8.3 — 2024-09-02
- 0.8.2 — 2024-07-24
- … 20 more at https://npm.io/package/@bolttech/frontend-foundations/versions

## README

[![N|Solid](https://www.bolttech.co.th/blog/wp-content/uploads/2020/10/logo.png)](https://bolttech.io)

# **Frontend-Foundations**

## **Summary**

On this documentation you will find the following topics:

- [Description](#markdown-header-description)
- [Requirements](#markdown-header-requirements)
- [Installation](#markdown-header-installation)
- [Before you start](#markdown-header-before-you-start)
  - [Screen breakpoints and Media Queries](#markdown-header-screen-breakpoints-and-media-queries)
  - [Default Theme](#markdown-header-default-theme)
- [Components](#markdown-header-components)
  - [BolttechThemeProvider](#markdown-header-bolttechthemeprovider)
  - [Row](#markdown-header-row)
  - [Column](#markdown-header-column)
  - [Center](#markdown-header-center)
  - [Typography](#markdown-header-typography)
- [Helper classes](#markdown-header-helper-classes)
  - [Colors](#markdown-header-colors)
  - [Margin](#markdown-header-margin)
  - [Padding](#markdown-header-padding)
  - [Positioning](#markdown-header-positioning)
- [Generating your own theme](#markdown-header-generating-your-own-theme)

## **Description**

The foundations are a set of components provided for developers to easily replicate the base used by the Designers to **_place, align, style and structure your pages._**

It contains a strict series of components that should always be used in your development, as it follows the [**_Bolttech Guidelines for designing pages._**](https://zeroheight.com/9a2ddf9f2/p/54487b-colors/b/24d401)

## **Requirements**

- [Node.js](https://nodejs.org/) 16.0 +
- [React](https://react.dev/) 18.2 +
- [Styled-components](https://styled-components.com/) 6.0 +

## **Installation**

Install the `frontend-foundations` package on your project, with the following command:

```sh
npm i @bolttech/frontend-foundations
```

For development environments:

```sh
git clone git@bitbucket.org:gofrank/frontend-foundations.git
cd frontend-foundations
npm install
npm run storybook
```

## **Before you start**

Before you start, you should be aware of two points that are the base of this project. Those points were defined in conjunction with the Design Team to create a basic structure that **should be followed everytime designing and developing new components and pages**. Those points are:

### **Screen breakpoints and Media Queries**

All of the components inside the foundations follow our breakpoint rules. Those rules are also used later for you to provide specific sizes for some components depending on which screen breakpoint the screen currently is. Those breakpoints are:

| Breakpoint | Screen Size    |
| ---------- | -------------- |
| **XS**     | <= 413px       |
| **SM**     | 414px - 767px  |
| **MD**     | 768px - 1439px |
| **LG**     | >= 1440px      |

With that said, you should import our `media-queries` based on those breakpoints when developing pages so you can better follow the grid guidelines.

#### Example:

```css
import styled from 'styled-components';
import { MediaQueries } from '@bolttech/frontend-foundations';

export const MyComponent = styled.div`
  display: flex;
  flex-direction: row;
  background-color: red;


  @media ${MediaQueries.LG} {
    background-color: green;
  }

  @media ${MediaQueries.SM} {
    flex-direction:column
  }
`
```

### **Default Theme**

The foundations comes with a preset of colors, paddings, spacings, typography and tokens, these presets are the `default theme` or `bolttech theme`.

Here is the structure of theme:

```typescript
type bolttechTheme = {
  colors: ColorsType;
  spacing: SpacingType;
  typography: TypographyType;
  effects: EffectType;
  components: Record<string, unknown>;
  tokens?: Record<string, unknown>;
};
```

## **Components**

### **BolttechThemeProvider**

The `BolttechThemeProvider` component is a extension of the [`ThemeProvider`](https://styled-components.com/docs/api#themeprovider) from styled-components. It allows you to inject a **theme** into all styled-components bellow it in the component tree.

Our `ThemeProvider` differs from the styled-components one because we expect a theme with a defined structure, and also, have a default theme with Bolttech styles.

If you want, you can import our **default theme** and the **theme type** and use it as you wish.

#### Example:

```jsx
import { BolttechThemeProvider, bolttechTheme } from '@bolttech/frontend-foundations';

const MyApp = () => (
  <BolttechThemeProvider theme={bolttechTheme}>
    <App />
  </BolttechThemeProvider>
);

export default MyApp;
```

**Important:** If you plan to use any of the components bellow, you **need** to wrap your application with the `BolttechThemeProvider` as our components use design tokens with a pre-defined structure, so you need to provide a theme with the type `BolttechThemeType`.

### **Box**
The Box component is a versatile container component for React applications, designed to provide flexible styling and layout options. It accepts various props to customize its appearance and behavior.

# React Box Component

## Overview

The `Box` component is a versatile container component for React applications, designed to provide flexible styling and layout options. It accepts various props to customize its appearance and behavior.

### Usage

```jsx
import { Box } from '@bolttech/frontend-foundations';

// ...

const MyComponent = () => {
  return (
    <Box
      sizes={{ xs: 100, sm: 100, md: 100, lg: 100 }} /* Optional */
      className="flex pt-l"
      removeGridPadding
      removeGridGap
    >
      {/* Your content goes here */}
    </Box>
  );
};
```

### Props

| Prop                | Type                                       | Default     | Description                                                               |
|---------------------| ------------------------------------------ | ----------- |---------------------------------------------------------------------------|
| `sizes`(Optional)   | `{ xs?: number; sm?: number; md?: number; lg?: number }` | `undefined` | Specifies the size of the component at different breakpoints.             |
| `className`         | `string | string[]`                        | `undefined`                                                               | Allows you to add custom CSS classes to the component.                  |
| `removeGridPadding` | `boolean`                                  | `false`     | If set to `true`, removes the default padding applied by grid class name. |
| `removeGridGap`     | `boolean`                                  | `false`     | If set to `true`, removes the default gap applied by grid class name.     |

### Ref forwarding

The `Box` component supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). You can use the `ref` prop to get a reference to the underlying `div` element.

```jsx
const myRef = useRef();

<Box ref={myRef}>Content</Box>;
```

### **Row**

The `Row` component is basicly a `div` that wraps the components as a flex container, applying the base styles of our [**Design Grid System**](https://zeroheight.com/9a2ddf9f2/p/872765-layout/b/786f73).

It has a **maximum width of 1440px**, a **gap between columns** and **paddings on both sides of the row**. The value of the gap and paddings are based on the Breakpoints of our grid system.

| Breakpoint | Gap        | Padding        |
| ---------- | ---------- | -------------- |
| **XS**     | flexbox.XS | flexbox.S      |
| **SM**     | flexbox.S  | flexbox.L      |
| **MD**     | flexbox.M  | flexbox['2XL'] |
| **LG**     | flexbox.M  | flexbox['3XL'] |

<br />

#### Props

| Prop           | Description         | Type                               | Required | Default     |
| -------------- | ------------------- | ---------------------------------- | -------- | ----------- |
| **fullWidth**  | remove row paddings | `boolean`                          | `false`  | `false`     |
| **fullHeight** | add 100% height     | `boolean`                          | `false`  | `false`     |
| **center**     | add margin 0 auto   | `boolean`                          | `false`  | `false`     |
| **className**  | extra css classes   | `string`                           | `false`  | `undefined` |
| **children**   | children component  | **ReactElement or ReactElement[]** | `false`  | `undefined` |

#### Example:

```jsx
import { Row } from '@bolttech/frontend-foundations';

<Row fullWidth={true} fullHeight={true} center={false} className="mb-xs">
  <ChildComponent />
</Row>;
```

### **Column**

The `Column` component is a component which uses **percentage of width** to define the size of the container. Designers and devs need to be aware that each screen breakpoint have a size to be filled. The possibilities of each breakpoint will be available below:

| Breakpoint    | Allowed Sizes                                           |
| ------------- | ------------------------------------------------------- |
| **XS**        | 100%, 75%, 66.666%, 50%, 33.333%, 25%, 0%               |
| **SM**        | 100%, 75%, 66.666%, 50%, 33.333%, 25%, 20%, 16.666%, 0% |
| **MD and LG** | 100%, 75%, 66.666%, 50%, 33.333%, 25%, 20%, 16.666%, 0% |

#### Props

| Prop          | Description                                                                 | Type                               | Required | Default     |
| ------------- | --------------------------------------------------------------------------- | ---------------------------------- | -------- | ----------- |
| **children**  | children component                                                          | `ReactElement` or `ReactElement[]` | `false`  | `undefined` |
| **className** | string containing a list of classes that need to be applied into the Column | `string`                           | `false`  | `undefined` |
| **size**      | object containing the size of the column for each breakpoint                | `Object`                           | `true`   |             |

#### Example:

```jsx
import { Column, Row } from '@bolttech/frontend-foundations';

const MyComponent = () => (
  <Row>
    <Column size={{ xs: '100%', sm: '33.333%', md: '50%', ld: '50%' }}>Hello</Column>
    <Column size={{ xs: '100%', sm: '66.666%', md: '50%', lg: '50%' }}>World</Column>
  </Row>
);
```

### **Center**

The `Center` component is a basic component that wraps it's children component and centers it.

#### Example:

```jsx
import { Center, Column, Row } from '@bolttech/frontend-foundations';

const MyComponent = () => (
  <Row>
    <Center>
      <Column size={{ xs: '50%', sm: '50%', md: '50%', lg: '50%' }}>World</Column>
    </Center>
  </Row>
);
```

### **Typography**

The `Typography` is a text component that can assume a lot of sizes determined by the design team based on the tokens inside the **typography file under the theme folder**. Please provide a valid combination of `variant` and `type` based on this file.

#### Props

| Prop          | Description                              | Type                               | Required | Default     |
| ------------- | ---------------------------------------- | ---------------------------------- | -------- | ----------- |
| **type**      | type of the typography                   | `string`                           | `true`   | `body`      |
| **variant**   | style variant                            | `string`                           | `true`   | `primary`   |
| **text**      | if you need to provide your text as prop | `boolean`                          | `false`  | `undefined` |
| **className** | extra css classes                        | `string`                           | `false`  | `undefined` |
| **children**  | children component                       | `ReactElement` or `ReactElement[]` | `false`  | `undefined` |

**Note:** Depending on what `type` and `variant` you provide, the `Typography` component will **render a different HTML Element**.

| Type         | Variant                            | Element |
| ------------ | ---------------------------------- | ------- |
| **headings** | `h1`, `h1Light`                    | `h1`    |
| **headings** | `h2`                               | `h2`    |
| **headings** | `h3`                               | `h3`    |
| **headings** | `h4`                               | `h4`    |
| **body**     | `primary`, `secondary`, `tertiary` | `p`     |
| **label**    | `primary`, `secondary`, `tertiary` | `label` |

#### Example:

```jsx
import { Typography } from '@bolttech/frontend-foundations';

const MyComponent = () => (
  <Typography variant="primary" type="body">
    Welcome to bolttech!
  </Typography>
);
```

Also, the `Typography` component can render links inside of its text. To render links, you should pass it as you would in a normal Markdown file, for example:

```jsx
const MyComponent = () => (
  <Typography variant="primary" type="body">
    normal text [text to render as link](https://google.com)(blank|download)
  </Typography>
);
```

Note that the last parameter is optional. If you dont pass it, it will open the link on the same tab

## **Helper classes**

To help the development and styling of your pages, we decided to add helper classes for **colors, paddings and margins** as we know that creating styled components just to add those properties is not a fun task.

All of those classes are created based on the colors, spacing and flexbox properties of the tokens provided by your theme configuration

With that said, we have a basic set of classes that we provide:

### **Colors**

Based on the structure of the theme, we create classes with the prefixes of `text-`, `bg-` and `fill-` and append the colors provided by your theme. So for example, if you have a theme with the following colors:

```ts
colors: {
  content: {
    accent: tokens.cyan['700'],
    base: tokens.navy['700'],
    subtle: tokens.navy['500'],
    weak: tokens.navy['400'],
    // ...
  }
}
```

We will inject the following classes on your global styles:

```css
.text-content-accent {
  color: #00bac7;
}
.bg-content-accent {
  background-color: #00bac7;
}
.fill-content-accent {
  fill: #00bac7;
}

.text-content-base {
  color: #170f4f;
}
.bg-content-base {
  background-color: #170f4f;
}
.fill-content-base {
  fill: #170f4f;
}
/* ... */
```

### **Margin**

Based on the structure of the theme, we create classes with the prefixes of `mt-`, `mb-`, `ml-`, `mr-`,`mh-`,`mv-`, and `m-`, and append the margins provided by your theme. So for example, if you have a theme with the following margins:

```ts
spacing: {
  flexbox: {
    XXS: '8px',
    XS: '16px',
    S: '24px',
    M: '32px',
    // ...
  },
}
```

We will inject the following classes on your global styles:

```css
.mt-xxs: {
  margin-top: 8px;
}
.mb-xxs {
  margin-bottom: 8px;
}
.ml-xxs {
  margin-left: 8px;
}
.mr-xxs {
  margin-right: 8px;
}
.mh-xxs {
  margin-left: 8px;
  margin-right: 8px;
}
.mv-xxs {
  margin-top: 8px;
  margin-bottom: 8px;
}
.m-xxs {
  margin: 8px;
}
```

### **Padding**

Based on the structure of the theme, we create classes with the prefixes of `pt-`, `pb-`, `pl-`, `pr-`,`ph-`,`pv-`, and `p-`, and append the paddings provided by your theme. So for example, if you have a theme with the following paddings:

```ts
spacing: {
  padding: {
    NONE: '0px',
    XXXS: '2px',
    XXS: '3px',
    XS: '4px',
    S: '8px',
    // ...
  },
}
```

We will inject the following classes on your global styles:

```css
.pt-xxs: {
  padding-top: 8px;
}
.pb-xxs {
  padding-bottom: 8px;
}
.pl-xxs {
  padding-left: 8px;
}
.pr-xxs {
  padding-right: 8px;
}
.ph-xxs {
  padding-left: 8px;
  padding-right: 8px;
}
.pv-xxs {
  padding-top: 8px;
  padding-bottom: 8px;
}
.p-xxs {
  padding: 8px;
}

/* ... */
```

### **Positioning**

We also wanted to provide an easy way for people to position elements on the page without having to create custom styled components just for positioning. So we also inject those classes on your global styles:

```css
.flex {
  display: flex;
}
.flex-row {
  flex-direction: row;
}
.flex-row-reverse {
  flex-direction: row-reverse;
}
.flex-column {
  flex-direction: column;
}
.flex-column-reverse {
  flex-direction: column-reverse;
}
.flex-shrink-1 {
  flex-shrink: 1;
}
.flex-shrink-0 {
  flex-shrink: 0;
}
.flex-grow {
  flex: 1;
}
.flex-grow-1 {
  flex-grow: 1;
}
.flex-grow-0 {
  flex-grow: 0;
}
.flex-basis-0 {
  flex-basis: 0;
}
.flex-basis-1 {
  flex-basis: auto;
}
.align-start {
  align-items: flex-start;
}
.align-center {
  align-items: center;
}
.align-right {
  align-items: flex-end;
}
.align-self-stretch {
  align-self: stretch;
}
.align-self-center {
  align-self: center;
}
.align-self-start {
  align-self: start;
}
.align-self-end {
  align-self: end;
}
.justify-left {
  justify-content: flex-start;
}
.justify-center {
  justify-content: center;
}
.justify-right {
  justify-content: flex-end;
}
.justify-between {
  justify-content: space-between;
}
.justify-evenly {
  justify-content: space-evenly;
}
.justify-arround {
  justify-content: space-arround;
}
.min-content {
  width: min-content:
}
.max-content {
  width: max-content:
}

/* ... */
```

### Typography

Generates CSS classes for typography that can be applied across your application, ensuring consistency in typography styling according to the theme specified. It caters to different text elements like headings, body text, and labels for both mobile and desktop breakpoints.

### Parameters

- **`theme: ThemeType`**: An object that contains typography settings under `typography` property for both mobile and desktop, each including `headings`, `body`, and `label`.

### Returns

A string containing CSS class definitions for the typography variants specified in the theme object.

### Usage

Ensure your theme object is structured to include `typography` settings for both mobile and desktop, with detailed styles for `headings`, `body`, and `label`.

```typescript
const theme = {
  typography: {
    mobile: {
      headings: { /* styles */ },
      body: { /* styles */ },
      label: { /* styles */ },
    },
    desktop: {
      headings: { /* styles */ },
      body: { /* styles */ },
      label: { /* styles */ },
    },
  }
};
```

Invoke `createTypographyClasses` with the theme object:

```typescript
const typographyClasses = createTypographyClasses(theme);
```

### Example CSS Output

```css
.ty-headings-h1 {
  font-weight: 700;
  line-height: 1.2;
  font-size: 2rem;
  letter-spacing: 0.5px;
}
/* Additional classes for body, label, and other headings */
```

### Flexbox Gap

Generates CSS classes for controlling gaps in flexbox layouts, utilizing the flexbox token values defined in the theme object. It supports custom prefixes for different gap sizes, allowing for a more flexible design system.

### Parameters

- **`theme: ThemeType`**: An object that contains flexbox token values under the `tokens.flexbox` property.

- **`prefix = ''`**: An optional string parameter to prefix the generated class names, allowing for customization and avoiding naming conflicts. Example prefixes: "sm:", "md:", "lg:".

### Returns

An array of strings, each representing CSS class definitions for gap, row-gap, and column-gap based on the theme's flexbox token values.

### Usage

Ensure your theme object includes flexbox token values under `tokens.flexbox`.

```typescript
const theme = {
  tokens: {
    flexbox: {
      xss: '4px',
      xs: '6px',
      s: '8px',
    }
  }
};
```

Invoke `createGapClasses` with the theme object, and an optional prefix if needed. Here's how to use it with "sm:", "md:", and "lg:" prefixes for different gap sizes:

```typescript
const smallGapClasses = createGapClasses(theme, 'sm:');
const mediumGapClasses = createGapClasses(theme, 'md:');
const largeGapClasses = createGapClasses(theme, 'lg:');
```

### Example CSS Output

```css
.sm:gap-s {
  gap: 8px;
}
.sm:rg-s {
  row-gap: 8px;
}
.sm:cg-s {
  column-gap: 8px;
}
/* Additional classes for medium "md:" and large "lg:" gaps */
```

### **Responsive**

On the foundations, we also provide you a way to style your components based on screen sizes, to deal with responsiveness. For every class that you use to style your components, you can also target a specific screen size, simply adding the prefix of the screen size you want to target on the class.

Our approach is **mobile first** so be aware that if you provide a class without any prefix, it will apply to all the screen size, but, for example, if you provide a class called `md:pt-xs` it will apply the class `pt-xs` to screen sizes `md` **and larger**!. If you want to add only to a specific screen size, you would need to add another class targeting screen sizes bigger than the one you are targeting.

```typescript
<Row className="pb-m sm:pb-s md:pb-xs lg:pb-xxs md:flex-grow-0 md:justify-between">
  <Column size={{ xs: '100%', sm: '33.333%', md: '50%', ld: '50%' }}>Hello</Column>
  <Column size={{ xs: '100%', sm: '66.666%', md: '50%', lg: '50%' }}>World</Column>
</Row>
```

## **Generating/updating your own theme**

If you need to update your theme or create a new one, please take a look at our [theme generator cli tool.](https://bitbucket.org/gofrank/bolttech-ui/src/main/libs/theme-generator/)

---
_Source: https://npm.io/package/@bolttech/frontend-foundations · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._