@codegouvfr/react-dsfr

The @codegouvfr/react-dsfr package is a React integration for the French Government Design System (DSFR). It provides a toolkit of advanced, type-safe React components that leverage the vanilla JS/CSS implementation of @gouvfr/dsfr.

Key Features:

• Type-Safe API: Fully documented and type-safe, though TypeScript usage is optional.
• DSFR Compliance: Always up-to-date with the latest DSFR evolutions, ensuring the same look and feel as the official @gouvfr/dsfr.
• SSR Ready: Optimized for Server-Side Rendering (SSR) to prevent white flashes during reload. Most components are ready for Server Components, while others are marked with "use client".
• Framework Compatibility: Seamless integration with Next.js (both Pages and App directories), Create React App, and Vite.
• Modular Distributions: Three modular distributions allow you to import only the components you need, preventing large bundle sizes.
• Advanced Integrations: Supports optional integration with MUI (adapting MUI components to look like DSFR), CSS-in-JS, i18n (internationalization), and routing libraries like react-router.

WARNING: This design system is intended exclusively for use on official French public service websites to facilitate citizen identification of government sites.

Use StatefulObservable to implement a signal pattern that allows you to wire non-React functions to React components without depending on external libraries like EVT.

It works by creating an observable value that can be updated outside of the React lifecycle, and then using a hook to trigger re-renders in React components whenever that value changes.

Key behaviors:

• Initialization: When created, it takes an initializer function.
• Attachment: Unlike StatefulEvt, StatefulObservable does not post a value immediately upon the first attachment.
• Evaluation: If the current value has not yet been evaluated, next() is called on the initial value returned by the initializer function.

import { createStatefulObservable, useRerenderOnChange } from "tools/StatefulObservable";

// 1. Create the observable with an initial value function
const $counter = createStatefulObservable(() => 0);

// 2. Update the value from anywhere (non-React code)
export function incrementCounter() {
    $counter.current++;
}

// 3. Use the hook in a component to subscribe to changes
export function Counter() {
    useRerenderOnChange($counter);

    const counter = $counter.current;

    return <span>Counter: {counter}</span>;
}

If you are developing on the @codegouvfr/react-dsfr repository, use the following commands to manage the environment, run Storybook, test applications, and execute tests.

Setup:

git clone https://github.com/codegouvfr/react-dsfr
cd react-dsfr
yarn

Running Storybook:

yarn storybook

Running Test Applications: These commands allow you to test the library in different environments:

• Create React App: yarn start-cra
• Vite: yarn start-vite
• Next.js 13 PagesDir (default): yarn start-next-pagesdir
• Next.js 13 AppDir: yarn start-next-appdir

Running Tests:

• Run all unit tests (test/runtime): yarn test
• Run a specific test (e.g., CSS variable resolution): npx vitest -t "Resolution of CSS variables"

# Setup
git clone https://github.com/codegouvfr/react-dsfr
cd react-dsfr
yarn

# Storybook
yarn storybook

# Test Apps
yarn start-cra
yarn start-vite
yarn start-next-pagesdir
yarn start-next-appdir

# Tests
yarn test
npx vitest -t "Resolution of CSS variables"

The copy-dsfr-to-public utility automates the management of DSFR static assets. It performs the following steps:

1. Locates Assets: It finds the @gouvfr/dsfr package within your node_modules to extract the source CSS and assets.
2. Identifies Required Files: It parses dsfr.min.css to identify all assets (images, fonts, etc.) referenced via url() functions, ensuring only actually used assets are copied.
3. Copies to Public: It creates a /dsfr directory inside your project's public folder (detected via index.html or standard patterns) and populates it with the required files.
4. Version Management: It writes a version.txt file inside the /dsfr folder containing the version of @gouvfr/dsfr used. If the version in version.txt matches the installed version, the script exits early to save time.
5. Cache Busting: It automatically modifies your index.html to append a version query parameter (e.g., ?v=1.2.3) to any hrefs pointing to the /dsfr/ directory, helping to prevent stale asset caching.

The newsletter prop can be configured in two ways:

1. With a Form: Requires a form object. You must provide a formComponent which is a function that receives children (the input and button) and returns a React node. This allows you to wrap the input in your own <form> element. You can also control the success state via the success boolean to show a success alert.

2. Without a Form: A simpler version where only buttonProps are required, rendering a standalone button (as a button or anchor).

Key NewsletterForm properties:

• success: boolean to trigger the success alert.
• successMessage: ReactNode to customize the success message.
• formComponent: A component that wraps the input and button.
• consentHint: ReactNode for the legal/consent text below the input.
• inputProps: Partial configuration for the email input (label, hint, placeholder, etc.).

<Follow
  newsletter={{
    title: "Newsletter Title",
    buttonProps: { children: "Subscribe" },
    form: {
      success: false,
      formComponent: ({ children }) => <form action="/api/subscribe" method="POST">{children}</form>,
      consentHint: "By subscribing, you agree to our terms.",
    },
  }}
/>

The Card component is a versatile container used to group related content. It supports various layouts (vertical, horizontal), image integration (via URL or custom component), and clickable states.

Key Layout Options

• Vertical (Default): Standard stacked layout.
• Horizontal: Uses the horizontal={true} prop. You can control the content/image ratio using the ratio prop with values '33/66' or '50/50' (mapped to tier and half classes).
• Image Integration:
  • Use imageUrl and imageAlt for a standard <img> tag.
  • Use imageComponent to pass a custom React node as the image.
• Clickable Card: Set enlargeLink={true} and provide linkProps to make the entire card act as a link.

import { Card } from '@codegouvfr/react-dsfr';

// Basic Vertical Card
<Card 
  title="Card Title" 
  desc="Card description text"
/>

// Horizontal Card with Image URL
<Card
  title="Horizontal Card"
  horizontal
  ratio="33/66"
  imageUrl="/path/to/image.jpg"
  imageAlt="Description"
/>

// Clickable Card
<Card
  title="Clickable Card"
  enlargeLink
  linkProps={{ href: '/destination' }}
  iconId="fr-icon-arrow-right"
/>

To use the DSFR design system in a Next.js project using the Pages Router, use createNextDsfrIntegrationApi to generate an integration object. This object provides a Higher-Order Component (HOC) withDsfr to wrap your App component and a dsfrDocumentApi to configure your _document.tsx.

Configuration Options

When calling createNextDsfrIntegrationApi, you can pass the following parameters:

Implementation Steps

1. Wrap your App: Use withDsfr in _app.tsx.
2. Augment your Document: Use augmentDocumentForDsfr in _document.tsx to handle server-side color scheme detection.
3. Apply HTML Attributes: Use getColorSchemeHtmlAttributes in _document.tsx to inject data-fr-scheme and data-fr-theme into the <html> tag.

import { createNextDsfrIntegrationApi } from '@codegouvfr/react-dsfr/next-pagesdir';

const { withDsfr, dsfrDocumentApi } = createNextDsfrIntegrationApi({
  defaultColorScheme: 'system',
  doPersistDarkModePreferenceWithCookie: true,
  preloadFonts: ['some-font-basename'],
});

// In _app.tsx
export default withDsfr(function App(props) {
  return <Component {...props} />;
});

// In _document.tsx
// Use dsfrDocumentApi.augmentDocumentForDsfr and dsfrDocumentApi.getColorSchemeHtmlAttributes