Introduction
CORE React is a React implemenation of Procore's design guidelines.
Install
It is recommended to install @procore/core-react from NPM.
or
Install the peer dependencies.
Install the optional peer dependencies if necessary.
Styles
Core React's styled components handle all style inclusion except for two cases that it expects a final client to provide:
- Border box and all elements
- Inter font family
Usage
Named imports support tree shaking and types.
Component Usage
Building experiences with CORE React applies compound component design. This design pattern mirrors an HTML structure and allows our React component APIs to match closer to familiar element composition of HTML, e.g. a ol has li as children, opposed to an ol taking a specific items or data prop attribute, the children is already an array! As components become more complex and UX heavy, children are utilized less and instead leverage render props, e.g. MultiSelect optionRenderer={() => 'Constant'}.
A single component import will have properties that are other components. The following are all React components
The subcomponents are expected to be children of the parent component.
With the exception of Form, a subcomponent should not have subcomponents as properties. A case like Modal.Header.Title should not exist, however a subcomponent can still expect a subcomponent as children, e.g.:
Composing with children provides freedom of adding addition markup and logic as components where necessary. Reference the composing guide to learn more about using core-react to create rich components.
As components increase in complexity and UX interactions, APIs shift from composition and rely on supplying props of data and getters.
When dealing with Form, the third subcomponent indicates a conditional render. Please review Form docs on how to customize the props per view. Only a single third component will be displayed at a time.
In the below example only Form.Text.Read will render because of view set above in <Form view="read">.
Versioning
CORE React follows semantic versioning. Support for our exports is documented through the root level type definitions and deprecation warnings with JSDoc. Using undocumented exports is discouraged.
Some components will have a new version that will eventually replace the current name and can contain breaking API changes, these components are prefaced with Next. NextThing will eventually be renamed to Thing. We recommend using the next component now to get ahead of breaking changes and rename the import for less line changes later, import { NextThing as Thing } from.