React Bulma Components

4.1.0 · active · verified Sun Apr 19

React Bulma Components is a library providing a comprehensive set of React components that directly implement the Bulma CSS framework, offering a declarative way to build user interfaces adhering to Bulma's design principles. The current stable version is 4.1.0, actively receiving patch and minor updates, with major versions (like v4.0.0) introducing significant breaking changes. Key differentiators include its compatibility across popular React frameworks such as Gatsby, Create React App, and Next.js. Since version 4, the library supports tree-shaking by default, optimizing bundle sizes. It also provides a unique `domRef` prop for passing refs to underlying DOM elements, bypassing React's `forwardRef` to reduce overhead in the React Dev Tools. Developers should note that some component APIs or naming conventions might diverge from official Bulma documentation, necessitating consultation of its Storybook documentation. The library expects Bulma CSS to be provided externally as a peer dependency, offering flexibility for custom SASS setups.

Common errors

```
Module not found: Can't resolve 'bulma/css/bulma.min.css'
```
cause The Bulma CSS framework is a peer dependency and must be installed and imported separately.

fix Run `npm install bulma` or `yarn add bulma`, then add `import 'bulma/css/bulma.min.css';` to your application's entry point (e.g., `index.js` or `App.js`).
```
TypeError: Cannot read properties of undefined (reading 'Input') (or similar for other Form sub-components)
```
cause Attempting to import Form sub-components (like Input, Field, Control) directly from 'react-bulma-components' instead of destructuring them from the 'Form' export.

fix Ensure you import `Form` and then destructure its properties: `import { Form } from 'react-bulma-components'; const { Input, Field, Control, Label } = Form;`
```
Warning: Function components cannot be given refs. Attempts to access this ref will fail. Did you mean to use React.forwardRef()?
```
cause Using the standard `ref` prop on a `react-bulma-components` component, which internally expects `domRef` for passing refs to the actual DOM element.

fix Change `ref={myRef}` to `domRef={myRef}` on the `react-bulma-components` component.

Warnings

breaking Bulma CSS is no longer bundled with the library and has been moved to a peer dependency. You must install and import Bulma CSS separately in your project.
Fix: Install Bulma via npm: `npm install bulma` and import it in your entry file: `import 'bulma/css/bulma.min.css';`
breaking The `<List />` component has been completely removed in version 4.
Fix: Migrate any usage of `<List />` to standard HTML list elements or implement a custom React component based on Bulma's list styling guidelines.
gotcha To pass a React ref to the underlying DOM element rendered by a `react-bulma-components` component, use the `domRef` prop instead of the standard `ref` prop. This is a deliberate design choice to avoid extra wrapper components from `React.forwardRef`.
Fix: Replace `ref={myRef}` with `domRef={myRef}` when attaching a ref to a `react-bulma-components` component.
gotcha The API and naming conventions for components in `react-bulma-components` may sometimes differ from the official Bulma documentation. Always refer to the library's Storybook for accurate component usage and available props.
Fix: Consult the official Storybook documentation at `https://react-bulma.dev/en/storybook` for specific component usage examples and prop definitions.
breaking Version 4.0.0 introduced significant internal and external changes, including new spacing modifiers and improved TypeScript support, which may require adjustments to existing codebases. No official migration guide was provided.
Fix: Carefully review the Storybook for each component and incrementally update your code. Pay close attention to prop changes and behavior differences.

Install

npm install react-bulma-components npm
yarn add react-bulma-components yarn
pnpm add react-bulma-components pnpm

Imports

Button
wrong:
```
const Button = require('react-bulma-components').Button;
```
correct:
```
import { Button } from 'react-bulma-components';
```
Named imports are recommended for tree-shaking, which is enabled by default since v4.0.0.
Form.Input
wrong:
```
import { Input } from 'react-bulma-components';
```
correct:
```
import { Form } from 'react-bulma-components';
const { Input, Field } = Form;
```
Form-related components (Input, Field, Control, Label) are nested properties of the 'Form' export and must be destructured from it.
Columns
wrong:
```
import Columns from 'react-bulma-components/lib/components/Columns';
```
correct:
```
import { Columns } from 'react-bulma-components';
```
Older versions might have used specific deep import paths. Since v4, direct named imports are the standard for all components to leverage tree-shaking.

Quickstart

This quickstart demonstrates how to import and use several core components like Button, Box, Section, and Container, while also ensuring the necessary Bulma CSS is loaded. It illustrates basic component composition and prop usage.

import React from 'react';
import 'bulma/css/bulma.min.css';
import { Button, Box, Section, Container } from 'react-bulma-components';

const App = () => {
  return (
    <Section>
      <Container>
        <Box>
          <p className="title is-4">Welcome to React Bulma Components</p>
          <Button color="primary" onClick={() => alert('Hello Bulma!')}>
            Click Me
          </Button>
          {' '}
          <Button color="link" renderAs="a" href="https://react-bulma.dev/" target="_blank" rel="noopener noreferrer">
            Visit Docs
          </Button>
        </Box>
      </Container>
    </Section>
  );
};

export default App;

view raw JSON →