Root
A code-only component that enables use of Forge in a page or page section.
The Basics
What it is
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.
How it works
- Doesn’t apply to this component.
When to use
- To use Forge components and styling in a page or page section of a React app
When not to use
- For pages that don’t use Forge components or styling
- For apps that aren’t built in React
What to use instead
Doesn’t apply to this component.
How to use
Doesn’t apply to this component.
Style
Design details
Doesn’t apply to this component.
Placement and hierarchy
Doesn’t apply to this component.
Content
Doesn’t apply to this component.
Demos
Coding
Developer tips
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.
Repository
Implementation links
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.
Import statements
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';