@yoast/ui-library
v4.0.0
Published
Yoast UI library
Downloads
453
Keywords
Readme
Welcome to the Yoast UI library
A React component library for building Yoast user interfaces. Please visit the Storybook for an interactive overview of all available components and examples on how to use them.
Important!
These components are UI components only and should remain free from business logic, translations, implementation details and other non-general concepts.
Installation
Start with installing the package and its peer dependencies from NPM:
yarn add @yoast/ui-library react react-dom
Setup
This package assumes the use of tailwindcss
for building CSS and therefore ships with Tailwind layered CSS. You can easily set up Tailwind using the @yoast/tailwindcss-preset
package.
In your tailwind.config.js
, make sure to include this package in your content
configuration to prevent Tailwind from purging its styles like so:
module.exports = {
presets: [ require( "@yoast/tailwindcss-preset" ) ],
content: [
// Include all JS files inside the UI library in your content.
"./node_modules/@yoast/ui-library/**/*.js",
"./path/to/your/content/**/*.js",
],
};
To include this packages CSS in your build, import it in your stylesheet before the Tailwind layers like so:
/* Import main CSS including all components. */
@import "@yoast/ui-library";
/* Tailwind layers */
@tailwind base;
@tailwind components;
@tailwind utilities;
Now that your CSS is set up, you can start using the React components. Always start your React tree with the Root
component, which provides a context for general options and a CSS classname for scoping this libraries CSS. Without it, components in this library will not render properly. Check out the Root
component in the Storybook.
import { Root, Alert } from "@yoast/ui-library";
export default () => (
<Root context={ { isRtl: false } }>
<Alert variant="success">
Congrats! You've successfully setup the UI library.
</Alert>
</Root>
);
Please note that the CSS scoping adds one level of CSS specificity. Therefore @yoast/tailwindcss-preset
does the following:
- Enables the
important
rule for all utilities. - Disables the Tailwind
preflight
styles (they are included in theRoot
component's CSS). - Configures
@tailwindcss/forms
to use theclass
strategy (they are included in theRoot
component's CSS).
Elements, components & patterns
To improve the flexibility and re-usability of this library its split into three layers: elements, components & patterns. Each layer adds upon the preceding layer in terms of complexity and specificity. The goal of this split is to provide the most useful interfaces for regular use cases, but to remain flexibile enough to handle edge case implementations that require a different structure. If, for instance, a component or pattern turns out to be too opinionated, you can always fall back to building with elements only without having to reinvent the wheel entirely.
Elements
The elements layer contains the simplest and stupidest components. They are the smallest building blocks. They are opinionated, will hardly ever contain internal state and basically represent regular HTML elements with some added branding. Examples of elements are the Button
, Input
and Title
components.
Components
The components layer contains more complex and smarter components. They are probably the most used building blocks. They are a little opinionated, will sometimes contain internal state and represent regular use case components that group multiple elements together into a friendly interface. Examples of components are the InputField
and other form field components, that provide an interface for adding labelling and error messaging to an input element.
Patterns
The patterns layer contains example implementations of standardized element/component combinations. They are not actually components you can import and use in your code, but function more as a reference on how to work with the UI library to create rich interfaces. Examples of patterns could be PageLayout
and Header
, that combine multiple elements/components/plain HTML elements.
The as
property
To make components in this library as flexible as possible, most of them implement the as
property pattern. The idea is simple: it allows you to render a component as every valid JSX element, so HTML elements or custom React components. It can be read in a sentence like this: "Render ComponentA
as ComponentB
". Popular examples are rendering an anchor that looks like a button, or a label that looks like a title:
import { Button, Title } from "@yoast/ui-library";
export default () => (
<>
<Button as="a" href="https://yoast.com">I look like a button but am actually an achor.</Button>
<Title as="label">I look like a title but am actually a label.</Title>
</>
);
Local development
The components in this library are developed in isolation inside a Storybook, a visual tool for building component libraries. Developing components in isolation helps keep the interfaces flexible while ignoring implementation details.
# Install dependencies
yarn install
# Run Storybook for local development
yarn storybook
# Build a static Storybook
yarn build:storybook
Contributions
If you've developed a React component that you think belongs in this library, feel free to reach out to the Components team or open a pull request and request a review from one of the Components teams developers.