Configuration

The asheeui.config.ts file is the central configuration for your AsheeUI project. It's optional (sensible defaults apply with no config at all), but using it lets you control theming, component defaults, and more from a single place.

Import#

import type { ExternalConfig } from "asheeui";

Shape of the config#

Precedence#

AsheeUI resolves values in this order, from highest to lowest priority:

1. Instance prop: set directly on the component instance (<Button variant="solid" />)
2. Component config: components.<name> in asheeui.config.ts
3. Theme default: top-level defaults (defaultVariant, defaultColor, defaultRadius, defaultTheme)
4. Built-in fallback: the library's internal default (shown in each component's props table)

If a value is set at a higher level, it overrides all lower levels. If no value is set anywhere, the built-in fallback is used.

Example

// asheeui.config.ts
export const config: ExternalConfig = {
  defaultVariant: "bordered",        // Level 3
  components: {
    button: {
      variant: "solid",              // Level 2
    },
  },
};

// app/page.tsx
<Button variant="ghost" />           // Level 1 → renders as ghost
<Button />                           // Level 2 → renders as solid
// A Button in any other component   // Level 3 → renders as bordered

Full example#

A realistic asheeui.config.ts touching every top-level key:

// asheeui.config.ts
import type { ExternalConfig } from "asheeui";

export const config: ExternalConfig = {
  defaultTheme: "dark",
  defaultVariant: "solid",
  defaultColor: "primary",
  defaultRadius: "md",

  color: {
    light: {
      primary: "#7c3aed",     // override built-in light primary
    },
    dark: {
      background: "#0c0a1a",  // override built-in dark background
    },
    "company-brand": {
      extends: "dark",        // new theme based on dark
      primary: "#f97316",
      background: "#1c0a00",
      foreground: "#fff7ed",
      border: "#7c2d12",
    },
  },

  components: {
    button: {
      variant: "solid",
      color: "secondary",
      radius: "full",
    },
    input: {
      variant: "bordered",
      radius: "sm",
    },
    toast: {
      variant: "bordered",
      placement: "bottom-right",
    },
  },
};

Per-component configuration#

Each component in AsheeUI can be configured individually under the components key. The available options are documented on each component's own page under Global Configuration.

Component config vs. top-level defaults

• Top-level defaults (defaultVariant, defaultColor, etc.) apply to every component that accepts that prop.
• Component config (components.button.variant) applies only to that specific component type, overriding the top-level default.

This means you can set a global default for all components, then override it for specific components as needed.

Built-in defaults#

The built-in defaults used when no configuration is provided:

{
  color: defaultColorConfig,  // light and dark themes
  defaultRadius: "md",
  defaultTheme: "system",
  defaultVariant: "solid",
  defaultColor: "primary",
  components: {},
}

Each component also has its own built-in fallback values for properties not covered by the top-level defaults. These are documented in each component's props table.