Skip to content

Consuming

This guide covers how to install components from the Mzizi portal, customize them after installation, and keep them updated.

Before installing components, ensure your project has:

  1. A components.json file (created by npx shadcn@latest init)
  2. The cn() utility in lib/utils.ts
  3. Tailwind CSS with the Five African Minerals tokens in globals.css

See the Installation guide for full setup instructions.

Terminal window
npx shadcn@latest add https://mzizi.dev/api/v1/ui/button
Terminal window
npx shadcn@latest add \
https://mzizi.dev/api/v1/ui/card \
https://mzizi.dev/api/v1/ui/badge \
https://mzizi.dev/api/v1/ui/dialog
Terminal window
npx shadcn@latest add https://mzizi.dev/api/v1/ui/use-toast
npx shadcn@latest add https://mzizi.dev/api/v1/ui/use-mobile
Terminal window
npx shadcn@latest add https://mzizi.dev/api/v1/ui/utils
npx shadcn@latest add https://mzizi.dev/api/v1/ui/circuit-breaker

When you install a component, the CLI automatically:

  1. Installs npm dependencies — packages like radix-ui, class-variance-authority, recharts
  2. Installs registry dependencies — other Mukoko components the installed component needs (e.g., dialog pulls in button)

You do not need to manually resolve dependencies.

Components are installed as local files in your project. A typical install creates:

components/
ui/
button.tsx ← Full source code, you own it

The file contains:

  • TypeScript source with full type annotations
  • CVA variant definitions
  • Radix UI primitive usage for accessibility
  • cn() class composition
  • data-slot attributes for styling hooks

Since components are local files, you can modify them freely:

// In components/ui/button.tsx
const buttonVariants = cva("...", {
variants: {
variant: {
default: "...",
outline: "...",
// Add your custom variant
cobalt: "bg-[var(--color-cobalt)] text-white hover:bg-[var(--color-cobalt)]/90",
},
},
})
// Change the default border radius
const buttonVariants = cva(
"inline-flex items-center justify-center rounded-xl ...", // Changed from rounded-md
{ ... }
)
interface ButtonProps extends React.ComponentProps<"button">,
VariantProps<typeof buttonVariants> {
loading?: boolean // Add custom prop
}

To update a component to the latest registry version:

Terminal window
npx shadcn@latest add https://mzizi.dev/api/v1/ui/button

This overwrites the local file. If you have made customizations:

  1. Commit your current changes to version control
  2. Run the update
  3. Review the diff and re-apply your customizations

You can also fetch component data via the API without the CLI:

Terminal window
# Get component metadata and source
curl https://mzizi.dev/api/v1/ui/button
# List all components
curl https://mzizi.dev/api/v1/ui

The JSON response includes the full source code in the files[].content field, which you can copy manually if needed.

  1. Install from the registry — do not copy-paste component code from the documentation
  2. Keep the utility function — components depend on cn() from @/lib/utils
  3. Maintain the token system — components reference CSS custom properties; ensure your globals.css has all required tokens
  4. Test after updates — verify visual consistency and behavior after updating components
  5. Track changes — use version control to track modifications to installed components