@ledgerhq/react-ui NPM

`@ledgerhq/react-ui`

Design and interface resources for React

This package contains React components and styles built on top of our design system and used internally at Ledger.

Reference

Installation

Package

npm i @ledgerhq/react-ui

Peer dependencies

This library uses styled components heavily and relies on it being installed separately (to avoid package duplication).

npm i styled-components

And (obviously) if React packages are not already installed:

npm i react react-dom

Usage

Provider

Before using the library components, the style provider must be imported and rendered once to provide the components with the right context.

import { StyleProvider } from "@ledgerhq/react-ui";

function Root({ children }) {
  // Selected theme palette can be either "dark" or "light".
  return <StyleProvider selectedPalette="light">{children}</StyleProvider>;
}

Components

Import the components from @ledgerhq/react-ui.

import { Text, Flex, Logos } from "@ledgerhq/react-ui";

function Hello() {
  return (
    <Flex flexDirection="column" alignItems="center" rowGap={12} p={12}>
      <Text color="neutral.c100">
        <Logos.LedgerLiveRegular />
      </Text>
      <Text variant="h1">Hello, world!</Text>
    </Flex>
  );
}

Fonts (optional but recommended)

Ledger fonts can be either imported or added manually to your project.

After picking a method add the fontsPath property to the StyleProvider component to automatically generate @font-face blocks and register the Inter and Alpha font families.

// Create a global css font style that will import the required fonts based on the fontsPath prefix.
<StyleProvider fontsPath="assets/fonts">

Import

Using the import requires you to use a bundler to export and save the files to the target folder.

import "@ledgerhq/react-ui/assets/fonts";

With webpack 5 the rule below will process the font files and save them in the src/assets/fonts folder.

{
  test: /\.woff2/,
  type: "asset/resource",
  generator: {
    filename: "assets/fonts/[name].woff2",
  },
},

Scoped Imports

If you are using a loader that saves the fonts with custom names (for instance when using create-react-app), you can use the fontMappings prop to map the font names.

// These imports return the path to the public folder where the loader saves the fonts during the build.
import HMAlphaMono from "@ledgerhq/react-ui/assets/fonts/HMAlphaMono-Medium.woff2";
import InterBold from "@ledgerhq/react-ui/assets/fonts/Inter-Bold.woff2";
import InterExtraBold from "@ledgerhq/react-ui/assets/fonts/Inter-ExtraBold.woff2";
import InterExtraLight from "@ledgerhq/react-ui/assets/fonts/Inter-ExtraLight-BETA.woff2";
import InterLight from "@ledgerhq/react-ui/assets/fonts/Inter-Light-BETA.woff2";
import InterMedium from "@ledgerhq/react-ui/assets/fonts/Inter-Medium.woff2";
import InterRegular from "@ledgerhq/react-ui/assets/fonts/Inter-Regular.woff2";
import InterSemiBold from "@ledgerhq/react-ui/assets/fonts/Inter-SemiBold.woff2";

// Map the font names with the file path.
const fontMap = {
  "HMAlphaMono-Medium": HMAlphaMono,
  "Inter-Bold": InterBold,
  "Inter-ExtraBold": InterExtraBold,
  "Inter-ExtraLight-BETA": InterExtraLight,
  "Inter-Light-BETA": InterLight,
  "Inter-Medium": InterMedium,
  "Inter-Regular": InterRegular,
  "Inter-SemiBold": InterSemiBold,
};

// The substring call is used to make the path relative (removes the prepending /).
const fontMappings = (name) => fontMap[name].substring(1);

/* … */

<StyleProvider fontPath="path/to/fonts" fontMappings={fontMappings}>

Manually

The .woff2 font files are located in the src/assets/fonts folder. You can host them yourself, use a CDN (see below) or process them with a bundler by importing them.

The important thing is to register fonts by adding @font-face blocks for the Inter and Alpha font families.

For instance using the unpkg.com CDN:

@font-face {
  font-family: "Alpha";
  src: url("https://unpkg.com/@ledgerhq/react-ui/assets/fonts/HMAlphaMono-Medium.woff2") format("woff2");
  font-weight: 100;
  font-style: normal;
}

Minimal Working Example

🌍 Hosted here.

Assuming dependencies, webpack and babel (or equivalents) are installed and configured.

import React from "react";
import ReactDOM from "react-dom";
import "@ledgerhq/react-ui/assets/fonts"; // all fonts are consumed by the bundler and outputted to /assets
import { StyleProvider, Text, Logos, Flex, Switch } from "@ledgerhq/react-ui";

function Root() {
  const [palette, setPalette] = React.useState("light");
  const isLight = palette === "light";

  return (
    <StyleProvider fontsPath="assets" selectedPalette={palette}>
      <Flex flexDirection="column" alignItems="center" rowGap={12} p={12}>
        <Text color="neutral.c100">
          <Logos.LedgerLiveRegular />
        </Text>
        <Text variant="h1">Hello, world!</Text>
        <Switch
          name="select-theme"
          checked={isLight}
          onChange={() => setPalette(() => (isLight ? "dark" : "light"))}
        />
      </Flex>
    </StyleProvider>
  );
}

ReactDOM.render(<Root />, document.getElementById("react-root"));