# @dxos/react-components

> A low-level design system for DXOS, comprising React components and plugins for Vite and ESBuild.

Latest version **0.1.40** (published 2023-04-18) · MIT license · 11 weekly downloads

## Install

```sh
npm install @dxos/react-components
pnpm add @dxos/react-components
yarn add @dxos/react-components
bun add @dxos/react-components
```

## Health

**Score 10/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

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

Negative: abandoned; low maintenance score; declining downloads.

## Facts

| | |
|---|---|
| Version | 0.1.40 |
| Published | 2023-04-18 |
| First published | 2021-10-20 |
| Weekly downloads | 11 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 41 |
| Unpacked size | 872.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | DXOS.org |
| Maintainers | zhenya-dxos, mykola-vrmchk, dxos-bot, richburdon, egorgripasov, marik_d, wittjosiah |

## Links

- npm: https://www.npmjs.com/package/@dxos/react-components
- Homepage: https://dxos.org
- Issues: https://github.com/dxos/dxos/issues
- npm.io page: https://npm.io/package/@dxos/react-components

## Dependencies (41)

- [rci](https://npm.io/package/rci.md) ^0.0.3
- [alea](https://npm.io/package/alea.md) ^1.0.1
- [i18next](https://npm.io/package/i18next.md) ^21.10.0
- [postcss](https://npm.io/package/postcss.md) ^8.4.21
- [jdenticon](https://npm.io/package/jdenticon.md) ^3.2.0
- [tailwindcss](https://npm.io/package/tailwindcss.md) ~3.2.7
- [autoprefixer](https://npm.io/package/autoprefixer.md) ^10.4.12
- [lodash.merge](https://npm.io/package/lodash.merge.md) ^4.6.2
- [qrcode.react](https://npm.io/package/qrcode.react.md) ^3.1.0
- [@dnd-kit/core](https://npm.io/package/@dnd-kit/core.md) ^6.0.5
- [react-i18next](https://npm.io/package/react-i18next.md) ^11.18.6
- [tailwind-merge](https://npm.io/package/tailwind-merge.md) ^1.10.0
- [@dnd-kit/sortable](https://npm.io/package/@dnd-kit/sortable.md) ^7.0.1
- [@headlessui/react](https://npm.io/package/@headlessui/react.md) ^1.7.3
- [tailwindcss-radix](https://npm.io/package/tailwindcss-radix.md) ^2.8.0
- [@dnd-kit/modifiers](https://npm.io/package/@dnd-kit/modifiers.md) ^6.0.0
- [@dnd-kit/utilities](https://npm.io/package/@dnd-kit/utilities.md) ^3.2.0
- [@tailwindcss/forms](https://npm.io/package/@tailwindcss/forms.md) ^0.5.3
- [tailwindcss-logical](https://npm.io/package/tailwindcss-logical.md) ^3.0.0
- [@radix-ui/react-slot](https://npm.io/package/@radix-ui/react-slot.md) ^1.0.1
- [@fontsource/fira-code](https://npm.io/package/@fontsource/fira-code.md) ^4.5.12
- [@radix-ui/react-toast](https://npm.io/package/@radix-ui/react-toast.md) ^1.1.3
- [@radix-ui/react-avatar](https://npm.io/package/@radix-ui/react-avatar.md) ^1.0.2
- [@radix-ui/react-dialog](https://npm.io/package/@radix-ui/react-dialog.md) ^1.0.3
- [@radix-ui/react-portal](https://npm.io/package/@radix-ui/react-portal.md) ^1.0.2
- [@radix-ui/react-select](https://npm.io/package/@radix-ui/react-select.md) ^1.2.1
- [@fontsource/roboto-flex](https://npm.io/package/@fontsource/roboto-flex.md) ^4.5.2
- [@radix-ui/react-context](https://npm.io/package/@radix-ui/react-context.md) ^1.0.0
- [@radix-ui/react-popover](https://npm.io/package/@radix-ui/react-popover.md) ^1.0.5
- [@radix-ui/react-toolbar](https://npm.io/package/@radix-ui/react-toolbar.md) ^1.0.3
- [@radix-ui/react-tooltip](https://npm.io/package/@radix-ui/react-tooltip.md) ^1.0.5
- [@radix-ui/react-checkbox](https://npm.io/package/@radix-ui/react-checkbox.md) ^1.0.3
- [@fontsource/space-grotesk](https://npm.io/package/@fontsource/space-grotesk.md) ^4.5.10
- [@radix-ui/react-primitive](https://npm.io/package/@radix-ui/react-primitive.md) ^1.0.2
- [@radix-ui/react-collection](https://npm.io/package/@radix-ui/react-collection.md) ^1.0.2
- [@radix-ui/react-collapsible](https://npm.io/package/@radix-ui/react-collapsible.md) ^1.0.2
- [@radix-ui/react-alert-dialog](https://npm.io/package/@radix-ui/react-alert-dialog.md) ^1.0.3
- [@radix-ui/react-compose-refs](https://npm.io/package/@radix-ui/react-compose-refs.md) ^1.0.0
- [@radix-ui/react-dropdown-menu](https://npm.io/package/@radix-ui/react-dropdown-menu.md) ^2.0.4
- [@radix-ui/react-navigation-menu](https://npm.io/package/@radix-ui/react-navigation-menu.md) ^1.1.2
- [@radix-ui/react-use-controllable-state](https://npm.io/package/@radix-ui/react-use-controllable-state.md) ^1.0.0

## Recent versions

- 0.1.40 (latest) — 2023-04-18
- 0.1.41-next.d517c89 (next) — 2023-04-18
- 2.33.9-dev.a2586ac4 (dev) — 2022-08-17
- 0.1.41-next.adfd7c6 — 2023-04-18
- 0.1.39 — 2023-04-14
- 0.1.38 — 2023-04-14
- 0.1.39-next.49cabf5 — 2023-04-14
- 0.1.39-next.90cb9b6 — 2023-04-14
- 0.1.37 — 2023-04-13
- 0.1.38-next.48f0513 — 2023-04-13
- 0.1.38-next.52086c1 — 2023-04-12
- 0.1.37-next.41339e7 — 2023-04-12
- 0.1.37-next.e183047 — 2023-04-12
- 0.1.37-next.f87f7ef — 2023-04-12
- 0.1.37-next.a2d78db — 2023-04-12
- … 685 more at https://npm.io/package/@dxos/react-components/versions

## README

# DXOS design system

The `react-components` package is the single source of truth for DXOS’s lower-level design system.

To get started, you’ll need to set up how you’ll build with this package, add peer dependencies, set up the provider, and set up theming.

## Set up the build…

### …with Vite

Using the design system requires opting-in in a few places, but by design it
otherwise needs no configuration.

#### 1. Add the Vite plugin

Add `@dxos/react-components` to the project’s dev dependencies, then extend the
project’s Vite config (`vite.config.ts`) to use it, e.g.:

```ts
// ...
import { ThemePlugin } from '@dxos/react-components/plugin';
// ...
export default defineConfig({
  // ...
  plugins: [
    // ...
    ThemePlugin({content: [
        resolve(__dirname, '../node_modules/@dxos/react-components/dist/**/*.mjs'),
        './index.html', './src/**/*.{js,ts,jsx,tsx}'
      ]}),
    // ...
  ]
  // ...
});
// ...
```

Ensure `content` contains globs for your project’s own files that will use Tailwind classnames, as well as any DXOS
design system packages your project uses, e.g.:

```
'./node_modules/@dxos/react-components/dist/**/*.mjs',
'./node_modules/@dxos/react-appkit/dist/**/*.mjs',
'./node_modules/@dxos/react-composer/dist/**/*.mjs',
```

#### 2. Reference the basic stylesheet

In the file which calls React DOM’s `createRoot` or `render`, add:

```ts
import '@dxosTheme';
```

### …with ESBuild

The ESBuild plugin is experimental and has several caveats noted below, proceed with caution.

#### 1. Add the ESBuild plugin

Add `@dxos/react-components` to the project’s dev dependencies, then extend the
project’s ESBuild config to use it, e.g.:

```ts
// ...
import { ThemePlugins } from '@dxos/react-components/esbuild-plugin';
// ...
void build({
  entryPoints: [/* ... */, resolve(__dirname, '../node_modules/@dxos/react-components/src/theme.css')],
  // ...
  plugins: ThemePlugins({
    outdir: resolve(__dirname, '../dist'),
    content: [
      resolve(__dirname, '../index.html'),
      resolve(__dirname, '../src/**/*.{js,ts,jsx,tsx}'),
      resolve(__dirname, '../node_modules/@dxos/react-components/dist/**/*.mjs')
      // other sources to scan
    ]
  })
});
// ...
```

Ensure `theme.css` from `react-components` is included as an entrypoint, and `outdir` passed to `ThemePlugins` is the same as
provided to ESBuild.

#### 2. Reference the basic stylesheet

Load the built stylesheet as appropriate for your project, e.g. simply add it to `index.html`:

```html
<link rel="stylesheet" href="./dist/node_modules/@dxos/react-components/src/theme.css"/>
```

Note that _this is not in your project’s node_modules directory_, it’s in your project’s `outdir`.

### …with your own build stack

This package exports both CJS and ESM builds of its components, though these are styled with Tailwind as the design token system. Any build stack can use the component builds in this package, you’ll just need to configure your build to handle Tailwind so that styles are applied correctly.

Follow the [Tailwind Framework Guides documentation](https://tailwindcss.com/docs/installation/framework-guides) relevant to your stack to see how that’s done, but make the following modifications:

- Use the Tailwind configuration from this package:
```ts
import tailwindcss from 'tailwindcss';
import { tailwindConfig } from '@dxos/react-components';
// ...
tailwindcss(
  tailwindConfig({
    content: [/* Wherever else Tailwind utility classes are used */],
    /* Optional params as neeeded */
  })
)
// ...
```
- Instead of adding the Tailwind directives to your own CSS, use or import this package’s `theme.css` (`react-components/dist/plugin/theme.css`) which adds the Tailwind directives itself.
- This package relies on font assets installed via npm as dependencies; if you’re seeing errors in the browser console or build logs about missing `.woff2` files, ensure your build can correctly resolve the import directives used in `theme.css` e.g. `@import '@fontsource/roboto-flex/variable-full.css'`.

If you have any issues integrating this package with your build, please file an issue including details about your build stack and what result you’re getting.

## Add peer dependencies

This package uses icons from `phosphor-icons`, but lists them as a peer dependency to avoid re-exporting that package; use your project’s package manager to add `phosphor-icons` as a dependency.

## Set up the provider

In order for the project to render correctly, wrap your app with `<ThemeProvider/>`.

## Set up theming

In order to display the correct theme, you need to mark `<html>` with the correct class _from the `<head>` tag_, otherwise it will flash the wrong theme:

```html
<head>
  <script>
    if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
      document.documentElement.classList.add('dark')
    } else {
      document.documentElement.classList.remove('dark')
    }
  </script>
</head>
```

If you want to keep up with `prefers-color-scheme`, add:

```js
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function(e){ if(e.matches){
  document.documentElement.classList.add('dark')
} else {
  document.documentElement.classList.remove('dark')
}})
```

You could combine the two with a script like this one:

```js
function setTheme(darkMode) {
  document.documentElement.classList[darkMode ? 'add' : 'remove']('dark')
}
setTheme(window.matchMedia('(prefers-color-scheme: dark)').matches)
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function (e) {
  setTheme(e.matches)
});
```

You can augment this predicate checking any preferences saved in `localStorage`, etc.

Note that you can apply this classname selectively further down the DOM tree if needed.

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