Global Config — ConfigProvider

Birdpaper UI exposes global configuration through ConfigProvider. You can customize component prefix, namespace, locale, size, z-index, and more. Child components inherit these settings automatically.

Basic Usage

Configure at Install Time

Pass a config object to app.use() so components register and receive global config:

import { createApp } from "vue";
import BirdpaperUI from "birdpaper-ui";
import "birdpaper-ui/theme/index.css";

const app = createApp(App);

app.use(BirdpaperUI, {
  prefix: "Bp", // Component register prefix
  namespace: "bp", // CSS namespace
  locale: "zh-CN", // Locale
  size: "default", // Global size
  zIndex: 3000, // Overlay base z-index
  emptyText: "No data", // Empty-state copy
  fontFamily: undefined, // Optional override for --bp-font-family
});

Configure at Runtime

Call provideGlobalConfig in setup to update global config dynamically:

<script setup>
import { provideGlobalConfig } from "birdpaper-ui";

provideGlobalConfig({
  locale: "en",
  size: "small",
});
</script>

Options

prefix	string	"Bp"	Global register name prefix. With "My", Button registers as <MyButton>
namespace	string	"bp"	CSS class namespace; prefixes all BEM class names (e.g. bp-button)
locale	string	"zh-CN"	Global locale code; affects built-in copy in DatePicker, TimePicker, Pagination, and similar components
size	ComponentSize	"default"	Default size for form controls such as Input, Select, and Button. Values: mini / small / default / large
zIndex	number	3000	Base z-index for overlays (Modal, Drawer, Tooltip, Message)
emptyText	string	"No data"	Default empty-state text for Table, Select, and similar components
fontFamily	string	—	Global font-family; writes --bp-font-family on :root. Omit to use the built-in system font stack

ComponentSize Type

type ComponentSize = "mini" | "small" | "default" | "large";

mini	22px	12px	Compact table cells, tag bars
small	28px	13px	Dense forms, dialogs
default	32px	14px	General use (default)
large	36px	14px	Emphasis, standalone form pages

Priority

Component props always win over global config:

Component prop > ConfigProvider global config > Component default

<template>
  <!-- Global size is small -->
  <bp-config-provider :config="{ size: 'small' }">
    <!-- ✅ Uses small (inherits global) -->
    <bp-input placeholder="Inherits global size" />

    <!-- ✅ Uses large (prop wins) -->
    <bp-input size="large" placeholder="Local override" />
  </bp-config-provider>
</template>

Namespace

Change namespace to customize the CSS class prefix for every component—useful when multiple libraries share a page:

app.use(BirdpaperUI, { namespace: "my-ui" });

<!-- Default -->
<button class="bp-button">...</button>

<!-- Custom -->
<button class="my-ui-button">...</button>

Component Register Prefix

Change prefix to customize globally registered component names:

app.use(BirdpaperUI, { prefix: "My" });

<!-- Default -->
<BpButton>Click</BpButton>

<!-- Custom -->
<MyButton>Click</MyButton>

z-index Management

When several overlays share a page, set zIndex to control stacking from one base value:

app.use(BirdpaperUI, { zIndex: 3000 });

Offsets from the base:

Modal	zIndex
Drawer	zIndex + 1
Tooltip	zIndex
Message	zIndex + 3

Font Family

Components use the CSS variable --bp-font-family (built-in system font stack) and do not inherit fonts from the host app or docs site. Override via config or CSS:

app.use(BirdpaperUI, {
  fontFamily: '"Helvetica Neue", Arial, sans-serif',
});

<bp-config-provider font-family='"Helvetica Neue", Arial, sans-serif'>
  <App />
</bp-config-provider>

:root {
  --bp-font-family: "Helvetica Neue", Arial, sans-serif;
}

Consuming Global Config in Components

Component authors can read global config with useGlobalConfig:

<script setup>
import { useGlobalConfig } from "@birdpaper-ui/hooks";

const { size, locale, zIndex, emptyText, fontFamily } = useGlobalConfig();

// Prefer component prop, fall back to global
const finalSize = computed(() => props.size || size.value);
</script>

TypeScript

import type { ConfigProviderContext, ComponentSize } from "birdpaper-ui";

const config: ConfigProviderContext = {
  prefix: "Bp",
  namespace: "bp",
  locale: "zh-CN",
  size: "default",
  zIndex: 3000,
  emptyText: "No data",
  fontFamily: '"Helvetica Neue", Arial, sans-serif',
};

All options are optional; unset fields use their defaults.