Root is a code-only component that enables the use of all Forge components and styling in React apps. Essentially, to use Forge, you must include this component in your code.

Root is placed in code at the head of the app, page, or page section. It isn’t visible to users; they see just the Forge components and styling, not the Root component itself.

• Doesn’t apply to this component.

• To use Forge components and styling in a page or page section of a React app

• For pages that don’t use Forge components or styling
• For apps that aren’t built in React

Doesn’t apply to this component.

Doesn’t apply to this component.

Doesn’t apply to this component.

Doesn’t apply to this component.

Doesn’t apply to this component.

Root is required at the head of any section of a React application that will include Forge components. It has 2 functions: providing a shared theme and adding CSS classes.

Theme

Root uses the React Context API to share a theme object with any components that need it. This has been used to isolate different versions of Forge CSS from each other when multiple Forge apps are on the same page. However, as of Forge 8.2.0, Forge supports the Shadow DOM. The Shadow DOM is a better system for keeping application styling from leaking to other apps.

CSS classes

Root renders a div with the class fe_f_all to ensure that all content and components under it render with correct Forge styles. It also adds any classes listed in rootClasses in the theme. Those classes are also applied to elements using React Portal to render outside of the Root component. Never try to add custom namespacing by wrapping the Root component in a div with your custom class name, as it won’t be applied to components using React Portal.

Implementation links

Root directory in Bitbucket

Implementation details

It is strongly recommended to familiarize yourself with the Forge source code. While this documentation is a best effort to document the intent and usage of a component, sometimes some features only become clear when looking at the source code. Also, looking at Forge's source code may help identify and fix bugs in either your application or Forge itself.

Storybook files

Forge maintains at least one storybook file per component. While the primary audience for these files is typically the Forge team, these storybook files may cover usages of the component not covered by a demo. The storybook for the latest version of forge can be found at go/forge-storybook.

Testing library

Forge strongly encourages using testing-library to write tests for your application.

"The more your tests resemble the way your software is used, the more confidence they can give you."

If you're having trouble testing a Forge component using testing-library, it would be a good idea to see how Forge tests its own components. For the most part, Forge tries to use screen.getByRole as much as it can, as that API provides the best feedback on a11y compliance. Forge discourages the use of document.querySelector and screen.getByTestId as both APIs encourage using implementation details to test your component, and discourage adding roles to your component.

With that being said, many of Forge's components were not built with accessibility in mind. These components do break the recommendations listed above.

In Nimbus applications

athenaOne serves the Forge bundle independently from your application's bundle. Importing Forge components directly from '@athena/forge' takes advantage of this feature.

import { Root } from '@athena/forge'

In standalone applications

Importing components using the exact path to the module takes advantage of webpack's tree shaking feature. Webpack will include only that module and its dependencies.

import Root from '@athena/forge/Root';

To use this import guidance, Typescript applications must use typescript >= 4.7.3, and should add this setting to their tsconfig.json file:

{
  "compilerOptions": {
    "moduleResolution": "Node16",
  }
}

If this setting doesn't work for your application, use this import statement instead:

import Root from '@athena/forge/dist/Root';