# Zid MUI

:::info [Storybook]
Visit [Zid MUI Storybook](https://ui.zid.sa/) for more details
:::


:::tip[]
### Recommended Use Case
If you are building an [Embedded Apps](https://docs.zid.sa/embedded-apps.md) inside Zid Dashboard, use one of the available Zid MUI options to ensure UI consistency and seamless integration with Zid’s design system.
:::

## What is Zid MUI?

[Zid MUI](https://ui.zid.sa/) is a UI library library built on the MUI design system, adhering to [Zid's brand guidelines](https://brand.zid.sa/). It provides shared components, icons, hooks, and theme utilities for building consistent UIs across Zid products.

---

## Why it matters
- Consistent Zid look & feel across all partner integrations
- Pre-built components following Zid's brand guidelines
- Faster UI development, no need to build common patterns from scratch
- RTL support out of the box

---

## How to use it?

### React Stack
Full React component library with MUI integration.

#### Install
```shell
pnpm add @zidsa/zidmui react react-dom use-debounce @mui/material @mui/lab @emotion/styled
```

#### Theme setup

```css
import { ThemeProvider, CssBaseline } from '@mui/material';
import { themeParcel } from '@zidsa/zidmui/theme/theme';

const App = ({ children }) => {
  return (
    <ThemeProvider theme={themeParcel}>
      <CssBaseline />
      {children}
    </ThemeProvider>
  );
}
```

#### Usage
```css
import { AppButton } from '@zidsa/zidmui/components/app-button';
import { AppInputBase } from '@zidsa/zidmui/components/app-input-base';
import { IconSearchLine } from '@zidsa/zidmui/icons/system/search-line';
import { useToggle } from '@zidsa/zidmui/hooks/use-toggle';
```

### CSS-Only Stack
For non-React projects (Vue, Angular, vanilla JS, etc.). Pure CSS with design tokens and component classes.

#### Install
```shell
pnpm add @zidsa/zidmui
```

#### Import the stylesheet

```css
/* Import all styles */
@import '@zidsa/zidmui/styles/index.css';

/* Or import individual components */
@import '@zidsa/zidmui/styles/colors.css';
@import '@zidsa/zidmui/styles/typography.css';
@import '@zidsa/zidmui/styles/components/button.css';
@import '@zidsa/zidmui/styles/components/input.css';
```

#### Font setup
Add IBM Plex Sans Arabic to your HTML:
```html
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans+Arabic:wght@400;500;600;700&display=swap" rel="stylesheet">
```

---

## Usage Example
### Button

```html
<!-- Primary contained button -->
<button class="zid-button zid-button--contained zid-button--primary zid-button--md">
  Submit
</button>

<!-- Secondary outlined button -->
<button class="zid-button zid-button--outlined zid-button--secondary zid-button--sm">
  Cancel
</button>

<!-- Disabled button -->
<button class="zid-button zid-button--contained zid-button--primary zid-button--md" disabled>
  Disabled
</button>
```

### Input
```html
<!-- Default -->
<div class="zid-input zid-input--md">
  <input type="text" class="zid-input__field" placeholder="Enter your name" />
</div>

<!-- With error state -->
<div class="zid-input zid-input--md zid-input--error">
  <input type="text" class="zid-input__field" placeholder="Email" />
</div>

<span class="zid-input-helper zid-input-helper--error">Invalid email</span>
```

### Alert
```html
<!-- Success Alert -->
<div class="zid-alert zid-alert--success">
  <div class="zid-alert__icon"><!-- icon svg --></div>
  <div class="zid-alert__content">
    <div class="zid-alert__title">Success</div>
    <div class="zid-alert__message">Your changes have been saved.</div>
  </div>
</div>
```