Consuming
This guide covers how to install components from the Mzizi portal, customize them after installation, and keep them updated.
Prerequisites
Section titled “Prerequisites”Before installing components, ensure your project has:
- A
components.jsonfile (created bynpx shadcn@latest init) - The
cn()utility inlib/utils.ts - Tailwind CSS with the Five African Minerals tokens in
globals.css
See the Installation guide for full setup instructions.
Installing components
Section titled “Installing components”Single component
Section titled “Single component”npx shadcn@latest add https://mzizi.dev/api/v1/ui/buttonMultiple components
Section titled “Multiple components”npx shadcn@latest add \ https://mzizi.dev/api/v1/ui/card \ https://mzizi.dev/api/v1/ui/badge \ https://mzizi.dev/api/v1/ui/dialognpx shadcn@latest add https://mzizi.dev/api/v1/ui/use-toastnpx shadcn@latest add https://mzizi.dev/api/v1/ui/use-mobileLibrary utilities
Section titled “Library utilities”npx shadcn@latest add https://mzizi.dev/api/v1/ui/utilsnpx shadcn@latest add https://mzizi.dev/api/v1/ui/circuit-breakerDependency resolution
Section titled “Dependency resolution”When you install a component, the CLI automatically:
- Installs npm dependencies — packages like
radix-ui,class-variance-authority,recharts - Installs registry dependencies — other Mukoko components the installed component needs (e.g.,
dialogpulls inbutton)
You do not need to manually resolve dependencies.
What you get
Section titled “What you get”Components are installed as local files in your project. A typical install creates:
components/ ui/ button.tsx ← Full source code, you own itThe file contains:
- TypeScript source with full type annotations
- CVA variant definitions
- Radix UI primitive usage for accessibility
cn()class compositiondata-slotattributes for styling hooks
Customization after install
Section titled “Customization after install”Since components are local files, you can modify them freely:
Adding a variant
Section titled “Adding a variant”// In components/ui/button.tsxconst buttonVariants = cva("...", { variants: { variant: { default: "...", outline: "...", // Add your custom variant cobalt: "bg-[var(--color-cobalt)] text-white hover:bg-[var(--color-cobalt)]/90", }, },})Adjusting styles
Section titled “Adjusting styles”// Change the default border radiusconst buttonVariants = cva( "inline-flex items-center justify-center rounded-xl ...", // Changed from rounded-md { ... })Extending props
Section titled “Extending props”interface ButtonProps extends React.ComponentProps<"button">, VariantProps<typeof buttonVariants> { loading?: boolean // Add custom prop}Updating components
Section titled “Updating components”To update a component to the latest registry version:
npx shadcn@latest add https://mzizi.dev/api/v1/ui/buttonThis overwrites the local file. If you have made customizations:
- Commit your current changes to version control
- Run the update
- Review the diff and re-apply your customizations
Using the API directly
Section titled “Using the API directly”You can also fetch component data via the API without the CLI:
# Get component metadata and sourcecurl https://mzizi.dev/api/v1/ui/button
# List all componentscurl https://mzizi.dev/api/v1/uiThe JSON response includes the full source code in the files[].content field, which you can copy manually if needed.
Best practices
Section titled “Best practices”- Install from the registry — do not copy-paste component code from the documentation
- Keep the utility function — components depend on
cn()from@/lib/utils - Maintain the token system — components reference CSS custom properties; ensure your
globals.csshas all required tokens - Test after updates — verify visual consistency and behavior after updating components
- Track changes — use version control to track modifications to installed components