---
title: "Global component defaults"
description: "Set default prop values once for every Maz-UI component through the MazUi plugin or the Nuxt module"
package: "maz-ui"
url: "https://maz-ui.com/guide/global-defaults"
---

# Global component defaults

> Set default prop values once for every Maz-UI component through the MazUi plugin or the Nuxt module

- Package: `maz-ui`
- Web: https://maz-ui.com/guide/global-defaults

Instead of repeating the same prop on every instance (`<MazBtn rounded-size="lg" />` everywhere), you can set a default once and let every component pick it up.

## Priority

A resolved prop always follows this order, from highest to lowest priority:

1. The prop set on the component instance
2. `defaults.<ComponentName>` (per-component default)
3. `defaults.global` (cross-cutting default)
4. The library's built-in default

A global default **never** overrides a prop set on the instance. Without any `defaults` config, every component keeps its built-in default, so this feature is fully opt-in and backward compatible.

## Vue

Pass `defaults` to the `MazUi` plugin:

```ts
import { MazUi } from 'maz-ui/plugins/maz-ui'
import { mazUi as mazUiPreset } from '@maz-ui/themes/presets/mazUi'
import 'maz-ui/style.css'

app.use(MazUi, {
  theme: { preset: mazUiPreset },
  defaults: {
    global: { roundedSize: 'lg' },
    MazBtn: { roundedSize: 'full' }, // wins over global for MazBtn
    MazCard: { bordered: false, elevation: true },
    MazContainer: { bordered: false },
  },
})
```

## Nuxt

Set it in `nuxt.config` under the `mazUi` key:

```ts
export default defineNuxtConfig({
  modules: ['@maz-ui/nuxt'],
  mazUi: {
    defaults: {
      global: { roundedSize: 'lg' },
      MazBtn: { roundedSize: 'full' },
      MazCard: { bordered: false, elevation: true },
    },
  },
})
```

## `global` vs per-component

- `defaults.global` holds **cross-cutting** props shared by many components: `roundedSize`, `size` and `flagSrc`. Set them once and every component that exposes them picks the value up.
- `defaults.<ComponentName>` holds **per-component** props (including booleans such as `bordered`, `elevation`, `padding`). A per-component entry always wins over `global`.

```ts
defaults: {
  global: { roundedSize: 'lg', size: 'sm' },
  MazBtn: { roundedSize: 'full' }, // MazBtn is 'full', everything else 'lg'
}
```

## Type safety

`defaults` is fully typed. Each component entry is typed as `Partial<ComponentNameProps>`, so you get autocompletion and a TypeScript error on an unknown or mistyped prop:

```ts
defaults: {
  MazBtn: { roundedSiz: 'lg' }, // ❌ TS error: 'roundedSiz' does not exist
}
```

## Globalizable props

| Prop | Type | Components |
| --- | --- | --- |
| `roundedSize` | `MazRoundedSize` (`'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'`) | `MazBtn`, `MazBtnGroup`, `MazContainer`, `MazInput`, `MazTextarea`, `MazTable`, `MazBadge`, `MazAlert`, `MazAvatar`, `MazSkeleton`, `MazTimeline` |
| `flagSrc` | `MazCountryFlagSrc` (URL template or function, e.g. `loadCountryFlag` from `maz-ui/country-flags`) | `MazSelectCountry`, `MazInputPhoneNumber` (see [flags source](../components/maz-select-country.md#flags-source)) |
| `size` | `MazSize` (`'mini' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`) | `MazBtn`, `MazBtnGroup`, `MazBadge`, `MazInput`, `MazSelect`, `MazSelectCountry`, `MazInputNumber`, `MazInputTags`, `MazInputPhoneNumber`, `MazCheckbox`, `MazRadio`, `MazRadioButtons`, `MazDropdown`, `MazPagination`, `MazTable`, `MazTimeline` |
| `bordered`, `elevation`, `padding`, `transparent`, `overflowHidden` | `boolean` | `MazContainer` |
| `bordered`, `elevation`, `padding`, `radius`, `scale`, `overflowHidden` | `boolean` | `MazCard` |

**Tip: Note**

Components whose `size` is a free CSS length (`MazSizeUnit`, e.g. `MazSpinner`, `MazAvatar`, `MazDrawer`, `MazSlider`, `MazCircularProgressBar`, `MazFullscreenLoader`) do not take the global `size` token - the value would not be valid for them. `MazAlert` and `MazTimeline` keep their own wider `roundedSize` scale; a `defaults.global.roundedSize` value still applies to them, and their extra steps (`2xl`, `3xl`) are reachable through their per-component entry.

## Relation to the theme system

This is **not** a duplicate of [`@maz-ui/themes`](https://maz-ui.com/ecosystem/themes.md). The theme system controls *what a token looks like* (the CSS value of `rounded-md`, `shadow-elevation`, colors…). Global defaults control *which prop value a component selects by default* (whether `MazBtn` defaults to `roundedSize="lg"`). Both work together: the theme defines what `lg` renders as, the defaults decide which step a component uses.