🍱 Bento

A component library of accessibility primitives for building React design systems.

Bento provides unstyled, accessible building blocks built on React Aria that you can use to create your own component library or design system. It embodies the "Primitives" concept - fundamental, highly customizable components with no business logic.

📦 Packages

Bento provides a comprehensive collection of primitives organized into three categories:

Components

• box - React context for passing configuration through component tree
• button - Button component with press interactions and disabled states
• checkbox - Checkbox controls supporting single, grouped, and indeterminate selections
• container - Polymorphic component that renders as any HTML element via as prop
• control - Form control primitive providing label and visually hidden input structure
• dismiss - Visually hidden, focusable dismissal control for accessible modal dismissal
• divider - Horizontal or vertical content separator
• environment - Swap or override any Bento component with custom implementations
• focus-lock - Focus management primitive for containing and controlling focus within a scope
• heading - Heading component with automatic level tracking through nesting
• icon - Icon component with lazy loading and sprite mode
• illustration - SVG illustration component with rotation and flip support
• listbox - List selection primitive for building Select, Combobox, and Menu
• portal - Render children into a target DOM container outside the component hierarchy
• pressable - Make any element clickable with keyboard and interaction state support
• radio - Radio button controls with single-selection group management
• text - Text component with alignment, wrapping, and line clamping

Hooks

• scroll-lock - Prevent document scrolling while exposing Bento debugging hooks
• use-data-attributes - Expose component state to DOM via data attributes for CSS styling
• use-props - Unify component and slot-based props with render prop support
• use-svg-sprite - Optimize repeated SVG usage by registering icons into shared sprite

Utilities

• create-external-store - Low-level external store for useSyncExternalStore hook integration
• error - Enhanced error objects with documentation links and support information
• internal-props - Internal prop passing mechanism bypassing slot system restrictions
• slots - Enable infinite component customization without exposing individual props
• storybook-addon-helpers - Auto-generate Storybook metadata from TypeScript types and JSDoc
• svg-parser - Parse SVG strings into React elements with custom node transformations
• to-attribute-value - Serialize JavaScript values into HTML attribute-compatible strings
• types - Centralized TypeScript type definitions shared across Bento packages

🚀 Getting Started

See individual package READMEs in packages/ for installation and usage instructions.

📖 Documentation

Our documentation is powered by Storybook and can be started by running:

npm start

From inside of the apps/docs folder. Storybook is configured to automatically scan our packages/** folder for .mdx and .stories.{ts|tsx} files. This allows our documentation to be co-located with the actual code.

The examples that are part of the Storybook documentation should be placed in the examples folder as individual component exports. This allows us to re-use the examples as part of our testing strategy, as well as run tests against our examples folder to ensure our documentation and examples are always up to date and working as expected.

🛠️ Development

Prerequisites

• Node.js >= 23
• npm >= 10

Setup

# Clone the repository
git clone https://github.com/godaddy/bento.git
cd bento

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm run test

📝 Conventional Commits

The repo is configured only to accept conventional commits as commit syntax. This is enforced using @commitlint.

🔄 Changesets

When contributing changes to packages, you must include a changeset:

npm run changeset

Select the affected packages, choose the version bump type (patch/minor/major), and write a description using conventional commit syntax (e.g., "fix: resolve issue", "feat: add feature", "docs: update readme").

Note: Documentation changes in packages should use patch version bumps with a docs: prefix, as they improve the published package for consumers and AI tooling.

The Changeset Bot will automatically comment on pull requests to remind you if a changeset is needed.

🤝 Contributing

We welcome contributions from the community! Please read our Contributing Guide to get started.

📄 License

MIT License - Copyright (c) 2025 GoDaddy Operating Company, LLC.

See LICENSE.md for details.