Zid MUI: build embedded-app screens that match the merchant dashboard

What Zid MUI is

Zid MUI is Zid's UI library. It's built on the MUI design system and follows Zid's brand guidelines, and it ships shared components, icons, hooks and theme utilities so products built for Zid look and behave consistently.

The docs recommend it for one case in particular: if you're building an embedded app that runs inside the Zid Merchant Dashboard, use one of the Zid MUI options so your screens stay consistent with Zid's design system. The docs list what you get:

• A consistent Zid look and feel across partner integrations.
• Pre-built components that follow Zid's brand guidelines.
• Faster UI work, because common patterns are already built.
• RTL support out of the box.

The package is @zidsa/zidmui on npm, under the MIT license. Every component is documented with live examples in the Zid MUI Storybook at ui.zid.sa.

React setup

The React stack is the full component library with MUI integration. Install it together with its peer dependencies:

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

At the time of writing, the current release (3.3.1) expects React 19.2, MUI 7 (@mui/material and @mui/lab) and use-debounce 10 as peers, so check your project's versions before you add it. Then wrap your app in MUI's ThemeProvider with the Zid theme. Each component, icon and hook has its own import path, so you only pull in what you use:

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

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

// Each component, icon and hook has its own import path
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';

How the theme works

themeParcel is a standard MUI theme, so everything inside the provider picks up Zid's palette, typography, shadows and component styles. Some details from the package itself:

• Typography: the font stack starts with IBM Plex Sans Arabic, the same font the docs ask CSS-only projects to load.
• Shape: a base border radius of 8px.
• Dark mode: the package also exports themeParcelDark from @zidsa/zidmui/theme/theme.dark.
• CSS tokens: the stylesheets define variables such as --zid-color-primary-600 and --zid-radius-md, with dark values under [data-theme="dark"].

Components worth knowing

Most React components use an App prefix. The ones you'll likely use most in an embedded app:

• Actions: AppButton, AppIconButton.
• Forms: AppInputBase, AppInputBaseSearch, AppCheckbox, AppRadioGroup, AppInputRadioCard, AppSwitch, AppSwitchGroup.
• Layout and content: AppCard, AppAccordion, AppTabs, AppListItem, AppTypography, and the StackRow and StackColumn helpers.
• Feedback: AppAlert, AppStatus, AppEmptyState, AppDialog, AppTooltip, AppPagination.
• Hooks: useToggle, useDebounceState, usePaginatedData, useCustomEventListener.

AppButton limits color and variant to the combinations the design system supports. For example, color="primary" only takes variant="contained", and color="secondary" takes text or outlined. Your editor's type checking will flag an unsupported pair.

Beyond components, the library ships icons grouped by category (system, arrows, business, finance and more), illustrations, and Zid, payment and delivery logos. Browse them in the Storybook before you draw your own.

No React? Use the CSS-only stack

For Vue, Angular, vanilla JS or any other stack, Zid MUI ships plain CSS with design tokens and component classes. Install the package:

pnpm add @zidsa/zidmui

In your stylesheet, @import '@zidsa/zidmui/styles/index.css'; loads everything. To load only what you need, import individual files instead, such as styles/colors.css, styles/typography.css, styles/components/button.css and styles/components/input.css. Then load IBM Plex Sans Arabic and use the component classes in your markup:

<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans+Arabic:wght@400;500;600;700&display=swap" rel="stylesheet">

<button class="zid-button zid-button--contained zid-button--primary zid-button--md">
  Submit
</button>

<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>

Fitting it into your embedded app

Zid MUI covers how your app looks. How it loads inside the dashboard is covered by the Embedded Apps guide, and both apply:

• Zid loads your Application URL in an iframe and appends a language parameter, for example ?token=...&language=en. A good practice is to set your page's language and direction from it, so Arabic screens render right to left.
• Every page served in the iframe still needs the CSP headers from the Embedded Apps guide, including frame-ancestors, or the dashboard blocks it.
• Keep access_token and authorization on your server. The UI layer should never receive them.

Before you submit, open your app inside the dashboard on a development store and compare it with the native screens around it, in both Arabic and English.