---
applyTo: "**/*.tsx,**/*.ts,**/*.scss"
---
# @cfx-dev/ui-components — Project Setup
## Installation
```bash
yarn add @cfx-dev/ui-components
# or
npm install @cfx-dev/ui-components
```
## Required CSS Variables
Define these on `html` in your root stylesheet:
```css
html {
--width: 100vw;
--height: 100vh;
--quant: calc(1rem * 0.25); /* base unit — ui.q(4) = 1rem */
}
```
## Import Global Styles
In your root JS/TS entry file, import the design system base styles:
```typescript
// CSS variables for all tokens (colors, spacing, typography, etc.)
import '@cfx-dev/ui-components/dist/styles-scss/global.scss';
// or CSS-only: import '@cfx-dev/ui-components/dist/assets/general/global.css';
// Default themes
import '@cfx-dev/ui-components/dist/styles-scss/themes.scss';
// or CSS-only: import '@cfx-dev/ui-components/dist/assets/general/themes.css';
// Component styles — all at once:
import '@cfx-dev/ui-components/dist/assets/all_css.css';
// or import per-component CSS as needed (tree-shaking friendly)
```
## Apply a Theme
Add a theme class to your `` or root element. Available themes:
- `cfxui-theme-cfx` — dark theme with pink accent (default)
- `cfxui-theme-fivem` — FiveM brand theme
- `cfxui-theme-redm` — RedM brand theme
- `cfxui-theme-wireframe` — neutral wireframe theme
```tsx
```
## SCSS Configuration (for projects using SCSS)
Create a forwarding file `ui.scss` in your styles directory:
```scss
@forward "~@cfx-dev/ui-components/dist/styles-scss/_ui.scss";
```
Then configure your bundler to auto-inject the `ui` namespace into all SCSS files:
```typescript
// vite.config.ts
css: {
preprocessorOptions: {
scss: {
additionalData: `@use "@/styles/ui" as ui;`,
},
},
}
```
This makes the full `ui.*` SCSS API (colors, spacing, typography, responsive mixins) available in every `.scss` file without manual imports.
## Required Providers
Wrap your app with `MediaQueryContextProvider` for responsive behavior:
```tsx
import { MediaQueryContextProvider } from '@cfx-dev/ui-components';
function App() {
return (
{/* your app */}
);
}
```
## Required DOM Outlets
Some components render via portals. Add these outlet elements to your root layout:
```tsx
{/* for BackdropPortal */}
{/* for Overlay / Modal */}
```
Optional outlets for specific components:
```tsx
{/* for Flyout */}
{/* for Title tooltips */}
```
The `Flyout` component also applies a shrink animation to your app root. Wrap your app content in an element with `id="cfxui-root"`:
```tsx
{/* your app content */}
```
## Copilot Instructions for Consuming Projects
To enable these Copilot instructions in projects that use this package, add to your VS Code workspace settings (`.vscode/settings.json`):
```json
{
"chat.instructionsFilesLocations": {
".github/instructions": true,
"node_modules/@cfx-dev/ui-components/copilot-instructions": true
}
}
```