@splunk/react-ui

A library of UI components that implement the Splunk design language in React.

Install

Install the package and its dependencies.

1. Install the peer dependencies:

   npm install react@^16 react-dom@^16 styled-components@^5

2. Install the package:

   npm install @splunk/react-ui

Production builds

@splunk/react-ui and React support production and development builds. The production build removes warnings and guidance from the output. To create a production build, set the environment variable NODE_ENV to "production" and use the webpack DefinePlugin to inject the variable into the code.

Use the components

Children

Nearly all components accept node children. Only components that require specific constraints include information about the children prop in its documentation.

Styling

• Pass style to control layout, margins, or positioning. See the following example:

  <Button label="Hello" style={{ flexBasis: '200px' }} />

• Alternatively, you can use a component's inline prop to switch between inline-block/inline-flex and block/flex. You can use this prop instead of passing a style prop. See the following example:

  <Button inline={false} />

• Avoid using className.

• Avoid overriding style sheets. When selector specificity changes, the change can break style sheet overrides.

The generated markup isn't an API and may change at any time without notice, even in a patch release. The selector specificity also isn't an API and may change at any time without notice.

Refs / elementRef

All components support an elementRef prop. It behaves similar to a React ref, but its value is guaranteed to be the main DOM element of the component, if mounted. In contrast, the value of a regular ref on a mounted class component is the component instance.

Defining fonts

The component library doesn't include fonts. You must define and load fonts in a @font-face declaration. By default, the components render in "Splunk Platform Sans", an alias of "Proxima Nova", and "Splunk Platform Mono", an alias of "Inconsolata".

Please make sure to obtain all required font licenses.

For quick reference, most themes use the following font-family stack:

Sans (default): Splunk Platform Sans, Proxima Nova, Roboto, Droid, Helvetica Neue,
    Helvetica, Arial, sans-serif;
Mono: Splunk Platform Mono, Inconsolata, Consolas, Droid Sans Mono, Monaco,
    Courier New, Courier, monospace;

Individual themes might use different fonts.

Version compatibility

It is strongly recommended to include only one instance of @splunk/react-ui in an application bundle. Likewise, using multiple instances of this library on the same page is discouraged.

| Multiple instances | @splunk/react-ui 4.x    | @splunk/react-ui 4.x and 3.x |
| ------------------ | ----------------------- | ---------------------------- |
| In the same bundle | Deduplicate             | Avoid                        |
| On the same page   | Avoid                   | Avoid                        |

In the same bundle

Multiple instances of @splunk/react-ui in the same bundle should be avoided. For example, instead of 4.0.0 and 4.1.0 only 4.1.0 should be used. Multiple versions of 3.x are not supported. Use a package manager (Yarn or NPM) or a module bundler (Webpack) to deduplicate versions.

1. Yarn or NPM:

yarn and npm resolve dependencies to avoid duplicate versions.

Pros:

• Supports 4.x and 3.x in the same bundle.

Cons:

• Extra versions can unexpectedly be added to lock files while updating dependencies.
• Upgrades may require rebuilding the lock file.
• All packages must all define their @splunk/react-ui dependency with a major version (@^4.0 or @^4.1), not a minor version (@~4.0).

2. Webpack:

Webpack's alias feature can force a single version of @splunk/react-ui to be used throughout the dependency tree.

Pros:

• Reliably builds with one version of @splunk/react-ui.

Cons:

• Cannot be used when 3.x and 4.x are required by different dependencies.
• If dependencies rely on a newer version, unexpected breakages may occur.

On the same page

While it's generally discouraged to run multiple instances of @splunk/react-ui on the same page, legacy environments exist that may have this requirement. A utility that can help with this scenario is LayerStackGlobalProvider in the Layer component.

Other libraries

If React Hooks are used, the react and react-dom packages should be deduplicated as described above.

styled-components, a dependency of this library, comes with its own rules and restrictions regarding multiple instances. It should always be deduplicated, and using its SC_ATTR feature is recommended. @splunk/webpack-configs enables it by default.

Further reading:

• styled-components and SC_ATTR
• styled-components "several instances" warning
• Duplicate React