This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
CoreUI for React is a comprehensive React.js components library built on top of Bootstrap 5 and TypeScript. It's organized as a monorepo using Lerna with multiple packages including the main React component library, icons, charts, and documentation.
This is a Lerna monorepo with the following key packages:
packages/coreui-react/- Main React components library (TypeScript)packages/coreui-icons-react/- Icon components for Reactpackages/coreui-react-chartjs/- Chart.js integration for Reactpackages/docs/- Gatsby-based documentation site
npm run lint- Lint all packagesnpm run test- Run tests for all packagesnpm run test:update- Update snapshots for all packages
npm run lib:build- Build main React librarynpm run lib:test- Test main React library onlynpm run lib:test:update- Update main library test snapshotsnpm run icons:build- Build icons packagenpm run charts:build- Build charts packagenpm run docs:dev- Start documentation dev servernpm run docs:build- Build documentation
Navigate to specific packages to run commands directly:
cd packages/coreui-react
npm test -- src/components/focus-trap/__tests__/CFocusTrap.spec.tsx # Run specific test
npm run build # Build this package onlyTo run a specific test file:
cd packages/coreui-react
npm test -- path/to/test.spec.tsxEach component follows a consistent structure:
components/[component-name]/
├── C[ComponentName].tsx # Main component
├── C[ComponentName]Part.tsx # Sub-components
├── index.ts # Exports
├── types.ts # TypeScript types (if complex)
├── utils.ts # Utility functions (if any)
├── const.ts # Constants (if any)
└── __tests__/ # Tests and snapshots
├── C[ComponentName].spec.tsx
└── __snapshots__/
Props Interface: All components have well-documented TypeScript interfaces with JSDoc comments focusing on accessibility and SEO benefits.
Ref Forwarding: Components forward refs properly to DOM elements for accessibility and integration.
Testing: Uses React Testing Library with Jest, focusing on behavior over implementation details. Each component has snapshot tests and behavioral tests.
Styling: Components use Bootstrap 5 classes and are compatible with @coreui/coreui CSS library.
TypeScript First: All components are written in TypeScript with proper type definitions.
Accessibility Focus: Components implement WCAG 2.1 standards and include proper ARIA attributes.
Bootstrap Compatible: Components extend Bootstrap 5 functionality while maintaining compatibility.
No Extra DOM: Many components avoid adding wrapper elements, using ref merging instead (see focus-trap component).
Utility Separation: Complex components separate utilities into dedicated files (utils.ts, const.ts).
- Snapshot tests for UI consistency
- Behavioral tests for user interactions
- Accessibility tests for focus management
- Props validation tests
- Jest with JSDOM environment
- React Testing Library for component testing
@testing-library/jest-domfor DOM assertions
Tests are run at the package level. Some complex focus management tests may not work perfectly in JSDOM but will work in real browsers.
Each package uses Rollup for building:
- ESM and CommonJS outputs
- TypeScript compilation
- Separate bundles for different environments
@coreui/coreui- Core CSS library@popperjs/core- For positioning (tooltips, dropdowns)prop-types- Runtime type checking- React 17+ peer dependency
- Follow the directory structure pattern
- Use TypeScript interfaces with comprehensive JSDoc
- Implement proper ref forwarding
- Add comprehensive tests (snapshot + behavioral)
- Export from package index files
- Consider accessibility from the start
When refactoring complex components:
- Separate utilities into
utils.tsand constants intoconst.ts - Maintain backward compatibility with existing props
- Update tests to match new structure
- Keep the same export interface
For components requiring focus management (modals, dropdowns), use the patterns established in the focus-trap component, which implements proper Tab/Shift+Tab cycling and external focus redirection.