Pentaho UI Kit

https://pentaho.github.io/uikit-docs/master
Admin
Pentaho UI Kit is an open-source React component library and design system built to streamline the...
Tokens:238,065
Snippets:1,225
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Manual setup: Initialize Vite project

Source: https://pentaho.github.io/uikit-docs/master/app-shell/installation

Start the manual setup by creating a new Vite project with the react-ts template.

```bash
npm create vite@latest my-app -- --template react-ts
```

--------------------------------

### Manual setup: Run development server

Source: https://pentaho.github.io/uikit-docs/master/app-shell/installation

Start the development server to run the App Shell application.

```bash
npm run dev
```

--------------------------------

### Install @pentaho/uikit-react-viz with bun

Source: https://pentaho.github.io/uikit-docs/master/components/charts

Use bun to install the visualization package.

```bash
bun add @pentaho/uikit-react-viz
```

--------------------------------

### Install @pentaho/uikit-react-viz with npm

Source: https://pentaho.github.io/uikit-docs/master/components/charts

Use npm to install the visualization package.

```bash
npm install @pentaho/uikit-react-viz
```

--------------------------------

### Install @pentaho/uikit-react-core with bun

Source: https://pentaho.github.io/uikit-docs/master/components

Install the core components package using bun.

```bash
bun add @pentaho/uikit-react-core
```

--------------------------------

### Install @pentaho/uikit-react-widgets

Source: https://pentaho.github.io/uikit-docs/master/components/canvas

Install the package containing the canvas components.

```bash
npm install @pentaho/uikit-react-widgets
```

--------------------------------

### Manual setup: Install App Shell Vite plugin

Source: https://pentaho.github.io/uikit-docs/master/app-shell/installation

Install the required App Shell Vite plugin as a development dependency.

```bash
npm install -D @pentaho/app-shell-vite-plugin
```

--------------------------------

### Install @pentaho/uikit-react-viz with yarn

Source: https://pentaho.github.io/uikit-docs/master/components/charts

Use yarn to install the visualization package.

```bash
yarn add @pentaho/uikit-react-viz
```

--------------------------------

### Install @pentaho/uikit-react-viz with pnpm

Source: https://pentaho.github.io/uikit-docs/master/components/charts

Use pnpm to install the visualization package.

```bash
pnpm add @pentaho/uikit-react-viz
```

--------------------------------

### Install @pentaho/uikit-react-core with yarn

Source: https://pentaho.github.io/uikit-docs/master/components

Install the core components package using yarn.

```bash
yarn add @pentaho/uikit-react-core
```

--------------------------------

### Install @pentaho/uikit-react-core with npm

Source: https://pentaho.github.io/uikit-docs/master/components

Install the core components package using npm.

```bash
npm i @pentaho/uikit-react-core
```

--------------------------------

### Install @pentaho/uikit-react-code-editor

Source: https://pentaho.github.io/uikit-docs/master/components/code-editor

Install the package using npm to use the CodeEditor component.

```bash
npm install @pentaho/uikit-react-code-editor
```

--------------------------------

### Install @pentaho/uikit-react-core with pnpm

Source: https://pentaho.github.io/uikit-docs/master/components

Install the core components package using pnpm.

```bash
pnpm add @pentaho/uikit-react-core
```

--------------------------------

### Install Packages with bun

Source: https://pentaho.github.io/uikit-docs/master/docs/get-started

Install the core UI Kit package along with required peer dependencies using bun.

```bash
bun add @pentaho/uikit-react-core @emotion/react @emotion/styled @mui/material
```

--------------------------------

### UnoCSS: Sizes and colors example

Source: https://pentaho.github.io/uikit-docs/master/docs/styling

Example of using utility classes for sizing and colors in a React component.

```jsx
<section className="flex items-center gap-sm">
  <div className="size-10 rounded bg-positive" />
  <div className="size-11 rounded bg-warning" />
  <div className="size-12 rounded bg-negative" />
  <div className="size-12 rounded bg-primaryDimmed" />
</section>
```

--------------------------------

### Install Packages with npm

Source: https://pentaho.github.io/uikit-docs/master/docs/get-started

Install the core UI Kit package along with required peer dependencies using npm.

```bash
npm i @pentaho/uikit-react-core @emotion/react @emotion/styled @mui/material
```

--------------------------------

### UnoCSS: Install UnoCSS and UI Kit plugin

Source: https://pentaho.github.io/uikit-docs/master/docs/styling

Installs UnoCSS and the @pentaho/uikit-uno-preset plugin as dev dependencies.

```bash
npm i -D unocss @pentaho/uikit-uno-preset
```

--------------------------------

### Install Packages with yarn

Source: https://pentaho.github.io/uikit-docs/master/docs/get-started

Install the core UI Kit package along with required peer dependencies using yarn.

```bash
yarn add @pentaho/uikit-react-core @emotion/react @emotion/styled @mui/material
```

--------------------------------

### Install Packages with pnpm

Source: https://pentaho.github.io/uikit-docs/master/docs/get-started

Install the core UI Kit package along with required peer dependencies using pnpm.

```bash
pnpm add @pentaho/uikit-react-core @emotion/react @emotion/styled @mui/material
```

--------------------------------

### app-shell.config.ts example

Source: https://pentaho.github.io/uikit-docs/master/app-shell/configuration

Example configuration file that exports a default object satisfying the HvAppShellConfig interface. It shows how to set name, baseUrl, navigationMode, and map app bare-specifiers to URLs.

```typescript
// app-shell.config.ts
import type { HvAppShellConfig } from "@pentaho/app-shell-vite-plugin";
 
export default {
  name: "App Name",
  baseUrl: "/",
  navigationMode: "ONLY_LEFT",
  apps: {
    "@hv-apps/my-app/": "https://example.com:3001/",
    "@hv-apps/another-app/": "https://example.com:5001/",
    "@hv-apps/other-app/someFile.js": "https://example.com:6001/someFile.js",
    "@hv-apps/other-app/entryPoint": "https://example.com:7001/index.js",
  },
  // ...
} satisfies HvAppShellConfig;
```

--------------------------------

### Implementing a Status Dropdown Menu

Source: https://pentaho.github.io/uikit-docs/master/examples/menus

This example shows how to use HvBaseDropdown to create a status-changing menu for items in a table. It defines a status configuration object to manage valid transitions and uses a custom component to handle the dropdown state and status updates.

```typescript
import { useState } from "react";
import {
  HvBaseDropdown,
  HvPanel,
  HvStatusIcon,
  HvTable,
  HvTableBody,
  HvTableCell,
  HvTableContainer,
  HvTableHead,
  HvTableHeader,
  HvTableRow,
  HvTableSection,
  HvTypography,
  type HvStatusIconVariant,
} from "@pentaho/uikit-react-core";


type AlertStatus = "Active" | "Acknowledged" | "Resolved" | "Suppressed";


const statusConfig: Record<
  AlertStatus,
  { variant: HvStatusIconVariant; next: AlertStatus[] }
> = {
  Active: {
    variant: "error",
    next: ["Acknowledged", "Suppressed"],
  },
  Acknowledged: {
    variant: "warning",
    next: ["Resolved", "Active"],
  },
  Resolved: {
    variant: "success",
    next: ["Active"],
  },
  Suppressed: {
    variant: "info",
    next: ["Active"],
  },
};


const initialAlerts = [
  { id: "1", name: "High CPU usage", asset: "Server-01", status: "Active" },
  {
    id: "2",
    name: "Disk space low",
    asset: "Storage-A",
    status: "Acknowledged",
  },
  { id: "3", name: "Network timeout", asset: "Router-02", status: "Active" },
  { id: "4", name: "Temp threshold", asset: "Sensor-07", status: "Suppressed" },
  { id: "5", name: "Memory leak", asset: "App-Server", status: "Resolved" },
] as { id: string; name: string; asset: string; status: AlertStatus }[];


function StatusDropdown({
  status,
  onChange,
}: {
  status: AlertStatus;
  onChange: (next: AlertStatus) => void;
}) {
  const [open, setOpen] = useState(false);
  const config = statusConfig[status];


  return (
    <HvBaseDropdown
      expanded={open}
      onToggle={(_, isOpen) => setOpen(isOpen)}
      placement="right"
      variableWidth
      classes={{
        root: "inline-flex! w-auto!",
        header:
          "border-transparent! bg-transparent! min-h-0! p-2px! rounded! hover:bg-bgHover! shadow-none!",
        arrowContainer: "hidden!",
        selection: "flex items-center",
      }}
      placeholder={
        <div className="flex items-center gap-xs cursor-pointer">
          <HvStatusIcon variant={config.variant} type="simple" />
          <HvTypography variant="label">{status}</HvTypography>
          <div className="i-ph-caret-down text-12px color-textSubtle" />
        </div>
      }
    >
      <HvPanel className="min-w-160px p-xxs flex flex-col">
        <HvTypography
          variant="caption2"
          className="color-textSubtle px-xs pt-xs pb-xxs"
        >
          Change status to
        </HvTypography>
        {config.next.map((next) => (
          <button
            type="button"
            key={next}
            className="flex items-center gap-xs px-xs py-xs rounded hover:bg-bgHover w-full text-left"
            onClick={() => {
              onChange(next);
              setOpen(false);
            }}
          >
            <HvStatusIcon variant={statusConfig[next].variant} type="simple" />
            <HvTypography variant="label">{next}</HvTypography>
          </button>
        ))}
      </HvPanel>
    </HvBaseDropdown>
  );
}


export default function Demo() {
  const [alerts, setAlerts] = useState(initialAlerts);


  const updateStatus = (id: string, next: AlertStatus) =>
    setAlerts((prev) =>
      prev.map((a) => (a.id === id ? { ...a, status: next } : a)),
    );


  return (
    <HvTableSection>
      <HvTableContainer>
        <HvTable>
          <HvTableHead>
            <HvTableRow>
              <HvTableHeader>Alert</HvTableHeader>
              <HvTableHeader>Asset</HvTableHeader>
              <HvTableHeader>Status</HvTableHeader>
            </HvTableRow>
          </HvTableHead>
          <HvTableBody>
            {alerts.map((alert) => (
              <HvTableRow key={alert.id}>
                <HvTableCell>{alert.name}</HvTableCell>
                <HvTableCell>{alert.asset}</HvTableCell>
                <HvTableCell>
                  <StatusDropdown
                    status={alert.status}
                    onChange={(next) => updateStatus(alert.id, next)}
                  />
                </HvTableCell>
              </HvTableRow>
            ))}
          </HvTableBody>
        </HvTable>
      </HvTableContainer>
    </HvTableSection>
  );
}
```

--------------------------------

### Automatic setup with @pentaho/uikit-cli

Source: https://pentaho.github.io/uikit-docs/master/app-shell/installation

Use the CLI tool to automatically create a new App Shell project.

```bash
npx @pentaho/uikit-cli@latest create my-app
```

--------------------------------

### Configure App Shell services

Source: https://pentaho.github.io/uikit-docs/master/app-shell/configuration

Example configuration object demonstrating instance, factory, and component service definitions using both direct values and bundle references with ranking and conditions.

```javascript
const appShellConfig = {
  services: {
    "my-app/services:UseCreateAction": [
      // Instance - direct value
      {
        instance: {
          value: {
            key1: "some value",
            key2: 11,
            key3: { nested: "value" },
          },
        },
        ranking: 10,
      },
      // Instance - module reference with conditions
      {
        instance: {
          bundle: "some-app/actions/create/useCreateReportAction.js",
        },
        ranking: 50,
        conditions: [
          {
            bundle: "@hv-apps/my-app/conditions/useHasReportPermission.js",
          },
        ],
      },
      // Factory - module reference
      {
        factory: {
          bundle: "some-app/factories/factory.js",
          config: { option: true },
        },
      },
      // Component - module reference with conditions
      {
        component: {
          bundle: "@my-app/components/HelloComponent.js",
          config: { name: "John" },
        },
        ranking: 50,
        conditions: [
          {
            bundle: "@hv-apps/my-app/conditions/useFeatureEnabled.js",
            config: { featureFlag: "hello-component" },
          },
        ],
      },
    ],
  },
};
```

--------------------------------

### Set Up HvProvider

Source: https://pentaho.github.io/uikit-docs/master/docs/get-started

Wrap your application root with HvProvider to enable theming and global configuration.

```javascript
// 1. import `Provider` component
import { HvProvider } from "@pentaho/uikit-react-core";
 
function App() {
  // 2. Wrap Provider at the root of your app
  return (
    <HvProvider>
      <YourApplication />
    </HvProvider>
  );
}
```

--------------------------------

### Automatic Installation via CLI

Source: https://pentaho.github.io/uikit-docs/master/docs/get-started

Use the UI Kit CLI to scaffold a preconfigured project with all necessary dependencies.

```bash
npx @pentaho/uikit-cli@latest create
```

--------------------------------

### Configure Main Panel Views

Source: https://pentaho.github.io/uikit-docs/master/app-shell/configuration

Example of configuring the main panel with specific views, routes, and container properties.

```javascript
const mainPanel = {
  maxWidth: "sm",
  views: [
    {
      bundle: "@hv-apps/my-app/pages/Hello.js",
      route: "/hello",
      config: {
        name: "John",
      },
    },
    {
      bundle: "@hv-apps/another-app/pages/Person.js",
      route: "/contacts/:name",
      maxWidth: "lg",
      fixed: true,
    },
  ],
};
```

--------------------------------

### HvRadio color prop examples

Source: https://pentaho.github.io/uikit-docs/master/components/radio

Demonstrates the `color` prop to style the radio. The example shows four radios with colors `primary`, `positive`, `coral`, and a custom hex color `#c73aa8`. The second line is the same example in a compact single-line form.

```jsx
<div className="flex gap-sm">
  <HvRadio checked color="primary" />
  <HvRadio checked color="positive" />
  <HvRadio checked color="coral" />
  <HvRadio checked color="#c73aa8" />
</div>

```

```jsx
<div className="flex gap-sm"> <HvRadio checked color="primary" /> <HvRadio checked color="positive" /> <HvRadio checked color="coral" /> <HvRadio checked color="#c73aa8" /> </div>
```

--------------------------------

### Example of a custom value renderer

Source: https://pentaho.github.io/uikit-docs/master/components/query-builder

A functional component example using the useQueryBuilderContext hook to dispatch value updates.

```typescript
const Renderer = ({ id }: HvQueryBuilderRendererProps) => {
  const { dispatchAction } = useQueryBuilderContext();
 
  return (
    <HvSlider
      required
      label="Slider"
      onChange={(value) => {
        dispatchAction({
          type: "set-value",
          id,
          value,
        });
      }}
    />
  );
};
```

--------------------------------

### Card with Media Example

Source: https://pentaho.github.io/uikit-docs/master/components/card

Shows how to use the HvCardMedia component to add an image to a card. The media component automatically adapts to its placement within the card.

```jsx
<HvCard className="w-240px" bgcolor="bgContainer">
  <HvCardMedia
    component="img"
    alt="Schedule New Job"
    height={120}
    image="https://s7d9.scene7.com/is/image/hitachivantara/take-charge-of-your-hybrid-cloud-estate-everflex-control-square:mediumvertical?fmt=webp"
  />
  <HvCardContent>
    <HvTypography>
      Use the live code editor to change the position of the `HvCardMedia`
      component in the card.
    </HvTypography>
  </HvCardContent>
</HvCard>
```

--------------------------------

### HvCheckBox labelPosition examples

Source: https://pentaho.github.io/uikit-docs/master/components/checkbox

Shows the labelPosition prop with left and right values. The second line is the same example in a single-line format.

```jsx
<div className="flex flex-col gap-sm">
  <HvCheckBox label="Label on the left" labelPosition="left" />
  <HvCheckBox label="Label on the right" labelPosition="right" />
</div>

```

```jsx
<div className="flex flex-col gap-sm"> <HvCheckBox label="Label on the left" labelPosition="left" /> <HvCheckBox label="Label on the right" labelPosition="right" /> </div>
```

--------------------------------

### HvOverflowTooltip usage example

Source: https://pentaho.github.io/uikit-docs/master/components/overflow-tooltip

Example of using HvOverflowTooltip with placement='top', paragraphOverflow={false}, and a long data string that triggers the tooltip when overflowing.

```jsx
<HvOverflowTooltip 
  placement="top"
  paragraphOverflow={false}
  data="This is a very long text that should be cut because it so long that it doesn't fit"
/>

```

--------------------------------

### Example translation JSON file

Source: https://pentaho.github.io/uikit-docs/master/app-shell/internationalization

Example of a JSON file containing translation keys and values. Each locale file uses this format.

```json
{
  "appName": "My Application",
  "pageOne": "Page One",
  "logoDesc": "Company logo"
}
```

--------------------------------

### Manual setup: Create app-shell.config.ts

Source: https://pentaho.github.io/uikit-docs/master/app-shell/installation

Define the App Shell configuration in the root directory using the HvAppShellConfig type.

```typescript
import type { HvAppShellConfig } from "@pentaho/app-shell-vite-plugin";
 
export default {
  logo: { name: "HITACHI" },
  menu: [
    {
      label: "Home",
      target: "/",
    },
  ],
  mainPanel: {
    views: [
      {
        route: "/",
        bundle: "$app/App.js",
      },
    ],
  },
} satisfies HvAppShellConfig;
```

--------------------------------

### HvRadio labelPosition examples

Source: https://pentaho.github.io/uikit-docs/master/components/radio

Shows the `labelPosition` prop to place the label on the left or right of the radio. The example renders two radios with labels "Label on the left" and "Label on the right" respectively. The second line is the same example in a compact single-line form.

```jsx
<div className="flex flex-col gap-sm">
  <HvRadio label="Label on the left" labelPosition="left" />
  <HvRadio label="Label on the right" labelPosition="right" />
</div>

```

```jsx
<div className="flex flex-col gap-sm"> <HvRadio label="Label on the left" labelPosition="left" /> <HvRadio label="Label on the right" labelPosition="right" /> </div>
```

--------------------------------

### Reference Shared Modules

Source: https://pentaho.github.io/uikit-docs/master/app-shell/configuration

Example of importing and using a module from a registered Application Bundle.

```javascript
import { getName } from "@hv-apps/another-app/modules/nameGenerator.js";
 
export default function Hello() {
  return <h1>Hello {getName()}!</h1>;
}
```

--------------------------------

### Hello.tsx module component

Source: https://pentaho.github.io/uikit-docs/master/app-shell/configuration

Example module component that receives the config object as props and renders a greeting. It is referenced by the module configuration example.

```tsx
// Hello.tsx
export default function Hello({ name, age }) {
  return <h1>{`Hello ${name} (${age})!`}</h1>;
}
```
Tokens:
Raw