Skip to main content

React Components Guidelines

This document provides code conventions and best practices for React components in the ProvLabs documentation website.

Component Structure​

File Organization​

  • Components are organized in src/components/ with subdirectories by type (e.g., ui/)
  • Use TypeScript for all React components (.tsx extension)
  • Export components using named exports and default exports appropriately

Component Definition​

  • Use React.forwardRef for reusable UI components that need ref forwarding
  • Set displayName on all forwardRef components for better debugging
  • Use TypeScript interfaces for props, extending appropriate HTML element types

Styling Conventions​

TailwindCSS Usage​

  • Use TailwindCSS for all styling - avoid custom CSS when possible
  • Utilize the cn() utility function from src/utils/index.ts for conditional classes
  • Leverage the twMerge and clsx pattern for className composition

className Patterns​

// Good: Using cn() utility for conditional and merged classes
const className = cn(
  'base-classes',
  conditionalClass && 'conditional-classes',
  props.className
);

// Consistent with existing table component pattern
className={cn('w-full caption-bottom text-sm', className)}

Style Overrides​

  • Use Tailwind's important modifier (!) sparingly and only when necessary
  • Prefer semantic class combinations over arbitrary values
  • Use consistent spacing and sizing utilities

Component Patterns​

Table Components​

  • Follow the existing table component structure in src/components/ui/table.tsx
  • Use forwardRef for all table-related components
  • Maintain accessibility with proper HTML semantics
  • Use consistent prop spreading: {...props}

Layout Components​

  • Use Docusaurus Layout component for page-level layouts
  • Implement responsive design with Tailwind responsive prefixes
  • Use semantic HTML elements with appropriate ARIA labels

TypeScript Conventions​

Props Interfaces​

// Extend appropriate HTML element interfaces
interface TableProps extends React.HTMLAttributes<HTMLTableElement> {
  // Additional props here
}

// Use React.forwardRef with proper typing
const Table = React.forwardRef<HTMLTableElement, TableProps>(
  ({ className, ...props }, ref) => (
    // Component implementation
  )
);

Event Handlers​

  • Use proper TypeScript event types
  • Prefer React synthetic events over native DOM events
  • Handle async operations properly with error boundaries

Accessibility​

ARIA Support​

  • Include appropriate ARIA labels and roles
  • Use semantic HTML elements as the foundation
  • Test with screen readers and keyboard navigation

Interactive Elements​

  • Ensure proper focus management
  • Include visible focus indicators
  • Support keyboard navigation patterns

Performance​

React Best Practices​

  • Use React.memo for expensive components that receive stable props
  • Avoid inline functions in render unless necessary
  • Use useCallback and useMemo judiciously

Bundle Optimization​

  • Import only necessary functions from libraries
  • Use tree-shaking friendly import patterns
  • Avoid importing entire icon libraries

Integration with Docusaurus​

  • Use @docusaurus/Link for internal navigation
  • Use regular <a> tags for external links with target="_blank" rel="noopener noreferrer"
  • Maintain consistent link styling with theme integration

Context Usage​

  • Use useDocusaurusContext for accessing site configuration
  • Leverage Docusaurus theme components when appropriate
  • Follow Docusaurus component swizzling patterns when customizing