This package has been deprecated

Author message:

Please use @chanzuckerberg/eds instead

@chanzuckerberg/eds-components

eds-components

React component library of the design system.

Setup

Fist install the package.

# via npm
npm install --save @chanzuckerberg/eds-components

# or, if using Yarn
yarn add @chanzuckerberg/eds-components

We currently use Arimo as our base font. This package does not export it, so you will need to import this separately. We recommend importing from Google Fonts into a top-level CSS file:

@import url("https://fonts.googleapis.com/css2?family=Arimo:wght@400;700&display=swap");

and setting up base font settings:

html {
  font-size: 16px;

  /* or if using Tailwind:
  @apply text-base */
}

body {
  font-family: Arimo, sans-serif;

  /* or if using Tailwind:
  @apply font-arimo */
}

Usage

Import any of the components from this package

import { Heading } from "@chanzuckerberg/eds-components";

and then use them in your React components

<Heading color="neutral" size="h2">
  Coffee!
</Heading>

Flow types

For any component, run

yarn generateFlowTypes <Component>

to get automatically generated flowtypes.

We use a combination of flowgen and common React mutations to get the best automatic types possible, but manual fixing may still be required. Thus, we recommend maintaining a flow-typed file with libdefs.

// declare a module for each component
declare module '@chanzuckerberg/eds-components/lib/<Component>' {
  ...
}

// re-declare each component from a root-level index
declare module '@chanzuckerberg/eds-components' {
  declare export var <Component>: $Exports<"@chanzuckerberg/eds-components/lib/<Component>">;
}

When translating your generated flow types to this flow-typed file, you will need to:

• Update React type imports to follow import type { ... } from "react"
• Update internal type imports to be from "@chanzuckerberg/eds-components/lib/..."
• Update ForwardRef components. For example:

declare var x: React.ForwardRefExoticComponent<{
  ...Props,
  ...React.RefAttributes<HTMLElement>,
}>;

should become:

import type { AbstractComponent } from "react";
declare var x: AbstractComponent<Props, HTMLElement>;

• Preserve exact-typed objects when possible. If you must make them inexact, add an explicit ... at the end of the object.

Tailwind Utility Classes

EDS Components is configured for TW utility class use in Storybook only. Please configure downstream Tailwind config purge to include app files if necessary.

Tailwind utility classes can be used with either @apply in CSS files such as

div {
  @apply rounded border-2;
  /* border-radius: 0.25 rem;
     border-width: 2px; */
}

or used directly as class names such as

<div className="rounded border-2">

Use the docs to search for appropriate classes.

Potential conflicts with other styling libraries (e.g. Bootstrap)

If you're also using styles from a separate library, conflicts may arise rarely between utility class names. Here are some conflicts we're aware of for Bootstrap specifically:

• Most annoying, .hidden
  • Both Tailwind and Bootstrap have the same styling for .hidden but Bootstrap applies the !important property, which can be annoying when trying to utilize Tailwind breakpoints, e.g.:

  <div class="hidden md:block lg:inline">

  • Where the expectation is display: none for breakpoints smaller than 768px, display: block for 768px - 1023px, and display: inline for >= 1024px. However since Bootstrap applies the !important property, all screen sizes show display: none.
  • This can be circumvented with the @apply directive and/or using custom CSS with regular media queries to scope styling into a different class name, e.g.:.

  <div className="responsive-display">

  .responsive-display {
    display: none;
    @apply md:block lg:inline;
    /* or use traditional @media queries */
  }

• .invisible and .text- alignment
  • These classes have the same styling in both Tailwind and Bootstrap, and therefore can be used without issues. Tailwind responsive states (such as breakpoints, hover, etc.) will have higher specificity so no issues will be caused there.
• Other unfound conflicts
  • If the conflict is due to Bootstrap using !important, follow similar strategy above as .hidden.
• Bootstrap styling and mentioned conflicts in _utilities.scss and _type.scss for reference