DOCSEARCHbyAlgolia
Submit Docs

Primer React

repository·main·Indexed 26 days ago

https://github.com/primer/react

A React implementation of GitHub's Primer Design System, providing reusable components and themes to build interfaces consistent with GitHub. The ecosystem includes @primer/react for components, @primer/primitives for design tokens, @primer/react-canvas for build-free components, and @primer/mcp for connecting AI tools to design tokens and patterns.

Tokens
49.4K
Snippets
89
Records
417
Agent score
87%

What's inside Primer React

  1. Overview of @primer/mcp

    main
    The @primer/mcp server is designed to bridge AI agents with the Primer design system. It enables AI tools to access and utilize Primer's design tokens, components, and patterns within local development environments or automated workflows like GitHub Actions.

  2. Understand @primer/styled-react architecture

    main
    The @primer/styled-react package provides a version of @primer/react components that optionally support sx and styled-system props. This package only includes components that have downstream sx usage across GitHub. It works by wrapping original @primer/react components to inject styling capabilities.

  3. Understand the Primer Spectrum of Abstraction model

    main

    Primer uses a layered abstraction model to provide a spectrum of component types, allowing developers to choose between speed of implementation and level of customization.

    • Config components: High-level, 'all-in-one' components. They are optimized for speed and follow established patterns using props/data. Use these for common use cases where you want Primer to manage state, accessibility, and styling automatically.
    • Presentational components: Mid-level components composed of 'parts'. They offer more flexibility by allowing you to control layout and content while Primer maintains the styling and semantics of the individual parts. These are typically used in conjunction with behavior hooks.
    • Base components: Low-level, unstyled primitives (e.g., accessibility primitives) used to build more complex components.
    • Utilities: Core hooks and functions (e.g., useMergedRefs, useOnEscapePress) used to build custom experiences on top of the foundations.

  4. Understand the Behavior architecture in Primer Components

    main

    Primer Components implements functionality through React Hooks, categorized into two types: Generic behaviors and Component behaviors.

    Generic Behaviors

    Low-level hooks that provide functionality not specific to any single component. They may only depend on other generic behaviors.

    • Examples: useProvidedRefOrCreate, usePosition, useClickAway, useTypeAhead.

    Component Behaviors

    High-level hooks that implement specific behaviors for components. They are built by combining one or more generic behaviors. A component may only use exactly one component behavior hook.

    • Examples: usePopover, useComboBox, useFilteredSearch, useDetails.

    Dependency Rules

    • Components can depend on Component behaviors and Generic behaviors.
    • Component behaviors can depend on Component behaviors and Generic behaviors.
    • Generic behaviors can only depend on other Generic behaviors.
    • Circular dependencies are strictly prohibited.

  5. Architectural decision for behavior isolation in Primer React

    main

    Primer React does not use Custom Elements for component behaviors due to complexities with ShadowDOM, SSR (isomorphism) compatibility, and styling limitations with styled-components. Instead, the project uses a hybrid approach:

    1. React Hooks: Used for behaviors that rely on user interactions/events (React SyntheticEvent vs native DOM events), shared state (React state management), or CSS styles (via styled-components).
    2. Vanilla JavaScript: Used for isolated portions of behaviors that have no dependencies other than the DOM. These vanilla implementations are then consumed within React Hooks to provide functionality to Primer React components.

    This decision ensures the library remains isomorphic and maintains a consistent developer experience with React's ecosystem.

  6. Understand the purpose of legacy-theme

    main
    legacy-theme provides a copy of the colors from dist in primer/primitives. It is intended as a temporary stopgap until the migration from JS variables to CSS variables is complete. Because it excludes the build logic from Primitives, every color value is provided as a raw hex code. Avoid making changes to these colors unless absolutely necessary.

  7. Access Primer React documentation

    main

    Detailed documentation for getting started, component references, themes, and design principles is available at the official documentation site.

    https://primer.style/react

  9. Use stable component identifiers for testing and selection

    main

    Primer components provide stable identifiers via the data-component attribute. This allows consumers to reliably target specific components or sub-components in unit, integration, and end-to-end tests, as well as for observability and tracking, without coupling to volatile CSS Module hashes or DOM structures.

    To select a specific component part, use a CSS selector targeting the data-component attribute with the component name (e.g., ActionList.Item).

  10. Upgrade to @primer/components v4.0.0-beta

    main

    The 4.0.0-beta release includes component renames and manual prop changes.

    Component Renames:

    • FlexContainer $\rightarrow$ Flex
    • FlexItem $\rightarrow$ Flex.Item
    • UnderlineNavItem $\rightarrow$ UnderlineNav.Item
    • FilterListItem $\rightarrow$ FilterList.Item

    Manual Changes Required:

    • Label: The scheme prop is removed. Use size and dropshadow props instead.
    • StateLabel: Use the scheme prop (replaces state) with updated values.
    npx jscodeshift -t node_modules/@primer/components/codemods/v4.js path/to/src

  11. Upgrade to @primer/components v2.0.0-beta

    main

    The 2.0.0-beta release renames several core components. To avoid conflicts, rename them in this specific order:

    1. Block $\rightarrow$ Box
    2. Box $\rightarrow$ BorderBox
    3. CaretBox $\rightarrow$ PointerBox
    npx jscodeshift -t node_modules/primer-react/codemods/v2.js path/to/src

  12. Design components using the Primer abstraction spectrum

    main

    Primer components are authored across four levels of abstraction. Use the appropriate type based on the intended use case:

    API typeUse for
    Config componentsReady-made, props-based components for stable product patterns and common use-cases. They provide opinionated defaults.
    Presentational componentsStyled pieces that consumers compose directly, often with companion behavior hooks. They allow control over layout and content.
    Base componentsUnstyled primitives used for accessibility structure or low-level behaviors (e.g., ButtonBase).
    UtilitiesHooks, state management, behaviors, and functions (e.g., useMergedRefs, useOnEscapePress) used to build components.