Tokens

Provider tokens extend the design-token maps that back props like color, size, rounded, and variant. Use this when remapping theme colors is not enough—for example a new brand color or a pill radius.

This is separate from the instance customProps / custom-props API on components, which forwards HTML attributes to internal parts.

How it works

Built-in tokens live in @bridge-ui/core (for example Button variant → color maps with base / hover / focus classes). Registry tokens deep-merges on top of those maps. Lookups use the merged tree, so <Button color="brand" /> resolves your classes when brand exists under the active variant.

Typical Button shape:

components: {
  Button: {
    tokens: {
      // new or overridden rounded token → class string
      rounded: Record<string, string>;
      // density → size → class string
      density: Record<string, Record<string, string>>;
      // variant → color → { base, hover, focus }
      variant: Record<
        string,
        Record<string, { base: string; hover: string; focus: string }>
      >;
    };
  };
}

Other components expose similar maps (color, size, padding, shadow, …)—see BridgeUIComponentsConfig in @bridge-ui/core.

Add a brand color

Define Tailwind utilities that use your theme tokens, then register them under each variant you need:

<script setup lang="ts">
import type { BridgeUIComponentsConfig } from "@bridge-ui/core";
import { BridgeUIProvider } from "@bridge-ui/vue";
import { Button } from "@bridge-ui/vue/Components/Button";

const components = {
  Button: {
    tokens: {
      variant: {
        outline: {
          brand: {
            base: "text-fuchsia-700 border border-fuchsia-600",
            hover: "hover:text-fuchsia-800 hover:bg-fuchsia-400/25",
            focus:
              "focus:border-transparent focus:text-fuchsia-800 focus:bg-fuchsia-400/25 focus:ring-fuchsia-600",
          },
        },
        solid: {
          brand: {
            base: "text-white bg-fuchsia-600 dark:bg-fuchsia-700",
            hover:
              "hover:text-white hover:bg-fuchsia-700 dark:hover:bg-fuchsia-600",
            focus:
              "focus:text-white focus:ring-offset-2 focus:bg-fuchsia-700 focus:ring-fuchsia-600 dark:focus:bg-fuchsia-600 dark:focus:ring-fuchsia-600",
          },
        },
      },
    },
  },
} satisfies BridgeUIComponentsConfig;
</script>

<template>
  <BridgeUIProvider :components="components">
    <div class="flex flex-wrap items-center gap-3">
      <Button color="brand">Brand</Button>

      <Button color="brand" variant="outline"> Outline </Button>
    </div>
  </BridgeUIProvider>
</template>

import type { BridgeUIComponentsConfig } from "@bridge-ui/core";
import { BridgeUIProvider } from "@bridge-ui/react";
import { Button } from "@bridge-ui/react/Components/Button";

const components = {
  Button: {
    tokens: {
      variant: {
        outline: {
          brand: {
            base: "text-fuchsia-700 border border-fuchsia-600",
            hover: "hover:text-fuchsia-800 hover:bg-fuchsia-400/25",
            focus:
              "focus:border-transparent focus:text-fuchsia-800 focus:bg-fuchsia-400/25 focus:ring-fuchsia-600",
          },
        },
        solid: {
          brand: {
            base: "text-white bg-fuchsia-600 dark:bg-fuchsia-700",
            hover:
              "hover:text-white hover:bg-fuchsia-700 dark:hover:bg-fuchsia-600",
            focus:
              "focus:text-white focus:ring-offset-2 focus:bg-fuchsia-700 focus:ring-fuchsia-600 dark:focus:bg-fuchsia-600 dark:focus:ring-fuchsia-600",
          },
        },
      },
    },
  },
} satisfies BridgeUIComponentsConfig;

export default function BrandColor() {
  return (
    <BridgeUIProvider components={components}>
      <div className="flex flex-wrap items-center gap-3">
        <Button color="brand">Brand</Button>

        <Button color="brand" variant="outline">
          Outline
        </Button>
      </div>
    </BridgeUIProvider>
  );
}

Add a rounded or size token

Button: {
  tokens: {
    rounded: {
      pill: "rounded-[2rem]",
    },
  },
},

<Button rounded="pill">Pill</Button>

Sizes and densities follow the same pattern: keys become prop values; values are the class strings (or nested maps) the component already expects for that axis.

Combine with defaults

Once a token exists, set it as the app default:

Button: {
  defaultProps: { color: "brand", rounded: "pill" },
  tokens: {
    /* brand + pill definitions */
  },
},

TypeScript

Runtime accepts any string key you register. For autocomplete and type-checking, augment the matching *Overrides interface—see Type overrides.

Next steps

Type overrides — ButtonColorOverrides, config augments, and more
Theme colors — remapping primary without new tokens
Classes — slot-level styling without new prop values