# smarthr-ui is a React component library with a theme, a Storybook and a charts package

> smarthr-ui is the shared UI component library behind the SmartHR product family, published on npm as React components that expect styled-components, React and React-DOM as peer dependencies. The library is developed in a pnpm workspace that also contains a separate charts package, and its release numbering has moved to a hundred based scheme that makes major version jumps easy to spot.

**kufu/smarthr-ui** — React components for creating SmartHR applications.

- Repository: https://github.com/kufu/smarthr-ui
- Website: https://story.smarthr-ui.dev
- Stars: 977 · Forks: 146
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/kufu-smarthr-ui

## A library that grew out of one company's internal apps

The README explains the origin in two sentences, and it is worth paraphrasing because it explains the shape of the library. SmartHR began as a set of core features and grew into a product with many optional features, and SmartHR UI exists to consolidate the user interface components of all of those applications into one place, with the stated goal of raising development productivity and the level of polish. That origin shows in the choices. The library is opinionated about styling, it ships its own theme provider rather than leaving design tokens to the consumer, and the component catalogue is the primary artifact rather than the source. The repository is a TypeScript project under the MIT licence, published on npm as `smarthr-ui`, with a Storybook deployment at story.smarthr-ui.dev that the README points at as the way to see the components on the master branch. It is a good example of a design system that grew from a product rather than being designed on a drawing board first.

## Installing it means the library and three peer dependencies

The package is on npm, and the installation is the ordinary one, with the three package managers shown side by side:

```sh
// with npm
npm install smarthr-ui

// with yarn
yarn add smarthr-ui

// with pnpm
pnpm add smarthr-ui
```

The part that matters is the second step. React, React-DOM and styled-components are peer dependencies, which means the library expects your application to provide them rather than installing its own copy:

```sh
// with npm
npm install react react-dom styled-components
```

The same command is shown for yarn and pnpm. This is the correct arrangement for a component library, since a library that bundles its own React would ship two copies of it, but it has a practical consequence. Your application decides the React version, and your application decides the styled-components version, and the library has to live with both. It also means the styling approach is not optional. styled-components is not a suggestion here, it is the mechanism the components are written in, so adopting the library means adopting that way of doing styles unless you are prepared to rewrite the components.

## The theme provider and the stylesheet are part of the contract

The usage example in the README is short and shows the whole integration. You import React, the React DOM client, and from the library `createTheme`, `ThemeProvider` and `Button`, and you import the stylesheet with `import 'smarthr-ui/smarthr-ui.css'`. You build a theme with `createTheme()` and wrap your tree in the `ThemeProvider`, and then the components read their colours, spacing and typography from that theme rather than from hardcoded values. The separate CSS import is the other half of the contract, since it carries the styles the library cannot express as a styled-component, and forgetting it is the kind of mistake that shows up as an unstyled page rather than an error. The pattern also means a consuming application can create more than one theme and switch between them by swapping the provider, which is the usual reason to require a theme provider at all rather than exporting a flat object of constants.

## The example wires in internationalisation from the start

One detail in the same example is easy to skim past and says a lot about the audience for the library. The app component wraps the tree in an `IntlProvider` with the locale set to `ja`, and the button's label is plain text inside the component. The internationalisation provider comes from a separate library, but the fact that the minimal example includes it tells you that localisation is part of the normal path for these components rather than an afterthought. The library itself is published by a Japanese team, and the README is written in Japanese, which is a reasonable signal that the components were designed with Japanese text in mind, where line breaking, label lengths and font stacks behave differently from English. The `smarthr-ui-charts` package, published separately under the `@smarthr` scope, follows the same pattern for chart components, and the root manifest keeps a script for each workspace so you can run the tooling for one package at a time.

## Storybook is the catalogue, and it is on the master branch

The component list is not in the README. The README points at the Storybook deployment and says the list of components on the master branch can be checked there, which is a deliberate choice, because a living catalogue stays in step with the code while a list in a readme goes stale. The Storybook is also why the toolchain is as heavy as it is. The root manifest carries eslint with the project's own config and a local rules directory, the perfectionist plugin for sorted imports and similar rules, the storybook eslint plugin, prettier with a Tailwind plugin and the project config, stylelint with several configurations including one for styled-components, knip for finding unused files and dependencies, and lint-staged with husky for the commit hooks. That is a lot of machinery, and it is all aimed at the same thing, keeping a large component set consistent. The release history is on the releases page, and the commit messages go through commitlint with the conventional configuration.

## A pnpm workspace with release-please and renovate

The repository is a pnpm workspace, with a `pnpm-workspace.yaml` and a `packages/` directory, and the root manifest is private and named `smarthr-ui`. It pins pnpm as the package manager at version 11.27.1 and keeps the two published packages addressable with a filter, one script pointing at the `smarthr-ui` package and one at `@smarthr/smarthr-ui-charts`. The release process is automated with release-please, and the presence of a release-please manifest and a matching config file in the root is what produces the tagged releases from conventional commits. Dependency updates are handled by renovate, with a renovate configuration file for the schedule and the rules. There is also a `sandbox/` directory, which is the place where a consuming application is assembled to try the components in a real app, and a `crowdin.yml`, which is the translation workflow, alongside a `.node-version` file that pins the Node version for everyone who clones the repository. A `CLAUDE.md` file at the root records instructions for coding agents working on the repository.

## Licence, design files and what the version numbers signal

The code is under the MIT licence, with the text in the LICENSE file, and the design side is documented separately. The design data is published on Figma as a community file, so the components can be inspected and extended by designers as well as developers. The SmartHR logo is a separate matter again: using it means reading the usage terms of the SmartHR Design System, which the README links. So the code is permissively licensed while the brand assets carry their own conditions, and that distinction is spelled out rather than left for a reader to discover in a legal page. On versions, the recent releases are `smarthr-ui-v100.1.0` on 2026-10-15, `smarthr-ui-v100.0.0` on 2026-10-08 and `smarthr-ui-charts-v0.3.0` on 2026-10-08. A jump to a hundred based scheme is what a team does when it wants major changes to be impossible to miss in a dependency update, and the last push to the repository was on 2026-10-20, so the work is current.

## Conclusion

smarthr-ui suits a team building a React application that wants a component set with a consistent design language, a theme provider, a Storybook for review and a charts package, and it suits anyone who values a design system whose source and its design files are both public. It is a poor fit if you need a library with no styling assumptions, since styled-components is a peer dependency and the components ship their own stylesheet, and it is a poor fit if your project is not React, since the peer dependency list ends the discussion there. Before you depend on it, check three things: the version you take, since the releases are numbered from v100 and a major bump here means a breaking change, the peer dependency versions you already have, since React, React-DOM and styled-components must be provided by your application, and the Figma and logo terms, because the design data is published separately from the code and the SmartHR logo comes with its own usage rules.

## FAQ

### How do I install smarthr-ui?

With `npm install smarthr-ui`, `yarn add smarthr-ui` or `pnpm add smarthr-ui`. React, React-DOM and styled-components are peer dependencies, so you also install those yourself with the package manager of your choice, and your application supplies the versions.

### What peer dependencies does smarthr-ui need?

React, React-DOM and styled-components. The library does not bundle its own copies, so your application controls the versions, and styled-components is the mechanism the components use for styling, which makes it a requirement rather than an optional extra.

### How do I theme smarthr-ui components?

Create a theme with `createTheme()` and wrap your application in the `ThemeProvider`, then import the stylesheet with `import 'smarthr-ui/smarthr-ui.css'`. The minimal example in the README shows both parts, and the stylesheet import is needed for the styles the library cannot express through styled-components.

### Where can I see the smarthr-ui components?

In the Storybook at story.smarthr-ui.dev, which the README names as the place to check the list of components on the master branch. The design data is published separately as a Figma community file.

### How often is smarthr-ui released?

The recent releases are v100.1.0 on 2026-10-15, v100.0.0 on 2026-10-08 and a separate smarthr-ui-charts v0.3.0 on 2026-10-08, and the last push to the repository was on 2026-10-20. The releases are produced by release-please from conventional commits.

## Sources

- [kufu/smarthr-ui on GitHub](https://github.com/kufu/smarthr-ui)
- [License: MIT](https://github.com/kufu/smarthr-ui/blob/master/LICENSE)
- [Project website](https://story.smarthr-ui.dev)
- [README](https://github.com/kufu/smarthr-ui/blob/master/README.md)
- [Releases](https://github.com/kufu/smarthr-ui/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kufu-smarthr-ui