Quick start

Add the Bento package to your project:

pnpm

pnpm add @buildo/bento-design-system

yarn

yarn add @buildo/bento-design-system

npm

npm install @buildo/bento-design-system

Here's how an hello world looks like:

import "@buildo/bento-design-system/index.css";
import "@buildo/bento-design-system/defaultTheme.css";
import { defaultMessages } from "@buildo/bento-design-system/defaultMessages/en";
import { BentoProvider, Title } from "@buildo/bento-design-system";

function App() {
  return (
    <BentoProvider defaultMessages={defaultMessages}>
      <Title size="large">Hello, World!</Title>
    </BentoProvider>
  );
}

Let's break this down:

import "@buildo/bento-design-system/index.css";

Here we are importing Bento's own stylesheet. This is required for Bento to work correctly and it must be imported only once in your application, generally near the root of your app.

import "@buildo/bento-design-system/defaultTheme.css";

This imports the default theme. This is the same theme used by the documentation, and it's useful to get started right away. We will see in the next secions how to customize the theme.

import { defaultMessages } from "@buildo/bento-design-system/defaultMessages/en";

Here we're importing the default messages, used by some of Bento components. Bento provides default messages for the English language, so that you can use them for a quick start, but in a localized application you will likely provide your own so to support multiple languages.

What are default messages?

Bento components are entirely agnostic when it comes to localization: all components accept the text to be display to the user as props.

Some specific props, however, are very repetitive and would be too tedious to pass them as props every time you use the component. Think of messages like "No options" when a SelectField has no options to show or accessibility labels like "Close", which are used to describe actions on icons.

Without the default messages, for example, you would need to pass dismissButtonLabel every time you use Chip:

<Chip label={label} color={color} dismissButtonLabel={dismissButtonLabel} />

whereas default messages allow Bento to make dismissButtonLabel optional, and let you override it only if needed:

// This uses the default message for `dismissButtonLabel`
<Chip label={label} color={color} />

// This overrides the default message
<Chip label={label} color={color} dismissButtonLabel={myCustomDismissLabel} />

Here are some sample default messages you can use as a starting point, once you're ready to customize them:

my-project/app/src/defaultMessages.ts

import { ComponentProps } from "react";
import { BentoProvider } from "..";

export const defaultMessages: ComponentProps<typeof BentoProvider>["defaultMessages"] = {
  Chip: {
    dismissButtonLabel: "Remove",
  },
  Banner: {
    dismissButtonLabel: "Close",
  },
  Modal: {
    closeButtonLabel: "Close",
  },
  SelectField: {
    noOptionsMessage: "No options",
    multiOptionsSelected: (n) => {
      const options = n > 1 ? "options" : "option";
      return `${n} ${options} selected`;
    },
    selectAllButtonLabel: "Select all",
    clearAllButtonLabel: "Clear all",
  },
  SearchBar: {
    clearButtonLabel: "Clear",
  },
  Table: {
    noResultsTitle: "No results found",
    noResultsDescription: "Try adjusting your search filters to find what you're looking for.",
    missingValue: "-",
  },
  Loader: {
    loadingMessage: "Loading...",
  },
  DateField: {
    previousMonthLabel: "Prev month",
    nextMonthLabel: "Next month",
  },
  TextField: {
    showPasswordLabel: "Show password",
    hidePasswordLabel: "Hide password",
  },
};

import { BentoProvider, Title } from "@buildo/bento-design-system";

In the last import, we're importing some components from Bento:

• BentoProvider is a React context provider that is required for Bento components to work. You must wrap your application with it in order to use Bento.
• Title is a typography component which is used for title text.

function App() {
  return (
    <BentoProvider defaultMessages={defaultMessages}>
      <Title size="large">Hello, World!</Title>
    </BentoProvider>
  );
}

Here we're finally rendering our first Bento component, showing "Hello, World!" on screen.