Installation

Install Package

Install Phi using your preferred package manager. The current package version is v1.0.0-beta.1.

npm

npm install @dicehub/phi@beta

pnpm

pnpm add @dicehub/phi@beta

yarn

yarn add @dicehub/phi@beta

Peer Dependencies

Phi expects Vue to already exist in your application.

pnpm add vue

TypeScript

Phi's published declarations support skipLibCheck: false with TypeScript's Bundler module resolution. You can keep dependency declaration checking enabled.

Optional Charts

Install ECharts only for applications that use charts.

pnpm add echarts@^6.0.0

import { Chart, TimeseriesChart, type PhiChartOption } from "@dicehub/phi/components/chart";

Chart components, palettes, legends, and chart types use this dedicated module. Change any previous imports of these exports from @dicehub/phi to@dicehub/phi/components/chart. Other components do not require ECharts.

Import Components

Import components from the main package or use granular imports for better tree-shaking.

Main Package Import

import { Button } from "@dicehub/phi";

Granular Import (Recommended)

import { Button } from "@dicehub/phi/components/button";

Ark UI Primitives

Phi is built on top of Ark UI. For advanced use cases where you need access to the underlying primitives, Phi re-exports primitives with both barrel and granular imports.

Barrel Import

import { Select, Dialog, Tabs } from "@dicehub/phi/primitives";

Granular Imports (Recommended)

import { Select } from "@dicehub/phi/primitives/select";
import { Dialog } from "@dicehub/phi/primitives/dialog";

Import Styles

Phi provides two CSS distribution options depending on your setup.

For Tailwind CSS Users (Recommended)

If your application uses Tailwind CSS, add Phi source files to your content configuration and import the styles. Import order matters — Phi styles must come before @import "tailwindcss" so that Phi's theme tokens are registered first.

@import "@dicehub/phi/styles/tailwind";
@import "tailwindcss";

@source "../node_modules/@dicehub/phi/dist";

For Standalone CSS

If your application does not use Tailwind CSS, use the standalone build with compiled styles.

import "@dicehub/phi/styles/standalone";

Portal Stacking

Phi renders overlays through body-level teleports: Dialog, Select, Combobox, Dropdown, Popover, Tooltip, Toasty, and CommandPalette. Phi applies its own overlay z-index values, so isolate your application root to stop the application's internal stacking contexts from painting above them. A sticky header with a large z-index is the usual culprit.

#app {
  isolation: isolate;
}

Tailwind CSS

<div id="app" class="isolate">
  <!-- application -->
</div>

If you render overlays into a custom teleport container, that container owns its own stacking context and needs the same treatment.

Usage Example

Here is a complete minimal example using Phi components with Tailwind CSS.

CSS File (app.css)

@import "@dicehub/phi/styles/tailwind";
@import "tailwindcss";

@source "../node_modules/@dicehub/phi/dist";

Component File (App.vue)

<script setup lang="ts">
import { Button } from "@dicehub/phi";
import "./app.css";
</script>

<template>
  <Button>Save</Button>
</template>

Blocks vs Components

Phi separates package exports from higher-level blocks that live inside your application codebase.

Components (NPM Exports)

Components are published as NPM exports and can be imported directly from the package. These are the core UI pieces like Button, Select, and Dialog.

import { Button, Dialog, Select } from "@dicehub/phi";

Use components when you need consistent, pre-styled UI primitives that integrate seamlessly with your application. Components are versioned, tree-shakeable, and receive automatic updates.

Blocks

Blocks are higher-level compositions for product flows. Phi ships two kinds:

• Package blocks are compiled package exports. DeleteResource is available today and imports like any other component.
• Source blocks such as Page Header and Resource List are copied into your application by the Phi CLI. You own and can customize the installed source.

import { DeleteResource } from "@dicehub/phi/blocks/delete-resource";

pnpm dlx @dicehub/phi@beta init
pnpm dlx @dicehub/phi@beta add PageHeader

Utilities

Phi also exports utility functions for common tasks.

import { cn } from "@dicehub/phi/utils";

// Merge class names with Tailwind
const className = cn("base-class", condition && "conditional-class");