npm package: @splunk/react-ui
Description: Library of React components that implement the Splunk design language
Author: Splunk Inc.
Latest version: 5.9.1

# @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:
    ```bash
    npm install react@^18 react-dom@^18 styled-components@^5
    ```
2. Install the package:
    ```bash
    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](https://webpack.js.org/plugins/define-plugin/) 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:
  ```js
  <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:
  ```js
  <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](https://reactjs.org/docs/refs-and-the-dom.html),
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 5.x    | @splunk/react-ui 5.x and 4.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.
Only major bug fixes will be supported in version `4.x`
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 `5.x` and `4.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 (`@^5.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 `5.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](https://styled-components.com/docs/advanced#avoiding-conflicts-with-thirdparty-styles-and-scripts)
* [styled-components "several instances" warning](https://styled-components.com/docs/faqs#why-am-i-getting-a-warning-about-several-instances-of-module-on-the-page)
* [Duplicate React](https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react)


## LLM Documentation

This package includes AI-optimized documentation in the `docs-llm/` directory for use with AI assistants and tools like MCP  servers. These markdown files provide comprehensive component documentation suitable for LLM consumption.

- **Location:** `node_modules/@splunk/react-ui/docs-llm/`
- **Contents:** Component documentation, usage examples, API reference, accessibility guidelines
- **Format:** Markdown files optimized for AI/LLM processing

The LLM documentation mirrors the standard documentation but is formatted specifically for machine consumption, enabling AI assistants to provide accurate guidance on component usage, props, and best practices.