VaneUI

Documentation

GitHub

Getting Started

Core Concepts Installation Usage Basics

Basic Components

Button Badge Chip Checkbox Label Code Divider Input

Layout Components

Section Container Row Col Stack Card Grid3 Grid4 Grid5 Grid6

Typography Components

Text Title PageTitle SectionTitle Link List ListItem

Customization

Theming Overview Using ThemeProvider Theme & ThemeOverride ThemeDefaults ExtraClasses CSS Variables

Customization

ThemeDefaults

Set default theme values across your application using themeDefaults.

The themeDefaults property in VaneUI's ThemeProvider allows you to set default boolean props for components throughout your application. This provides a powerful way to establish consistent defaults while still allowing individual components to override these values.

Understanding ThemeDefaults

themeDefaults?: ThemeDefaults

The themeDefaults property accepts an object where keys are component names and values are objects with boolean props. These defaults are merged with VaneUI's built-in defaults.

<ThemeProvider themeDefaults={{
  button: { primary: true, md: true, filled: true },
  badge: { success: true, sm: true, pill: true },
  card: { secondary: true, rounded: true },
  text: { primary: true }
}}>
  <App />
</ThemeProvider>

Setting Component Defaults

Basic Defaults

Set default boolean props for specific component types:

import { ThemeProvider, Button, Badge, Card } from '@vaneui/ui';

function App() {
  return (
    <ThemeProvider themeDefaults={{
      button: {
        primary: true,   // All buttons are primary
        lg: true,        // All buttons are large
        filled: true     // All buttons are filled
      },
      badge: {
        success: true,   // All badges are success color
        pill: true       // All badges are pill-shaped
      },
      card: {
        rounded: true,   // All cards have rounded corners
        border: true     // All cards have borders
      }
    }}>
      {/* Components use these defaults automatically */}
      <Button>Primary Large Filled Button</Button>
      <Badge>Success Pill Badge</Badge>
      <Card>Rounded Card with Border</Card>
    </ThemeProvider>
  );
}

Brand-Specific Defaults

Create consistent branding across your application:

import { ThemeProvider, Button, Card, Badge } from '@vaneui/ui';

function BrandedApp() {
  return (
    <ThemeProvider themeDefaults={{
      button: { brand: true, filled: true, rounded: true },
      card: { brand: true, rounded: true },
      badge: { brand: true, pill: true }
    }}>
      <nav>
        <Button>Home</Button>
        <Button>About</Button>
        <Badge>New</Badge>
      </nav>
    </ThemeProvider>
  );
}

Available Boolean Props

Size Props

xs, sm, md, lg, xl

Appearance Props

primary, brand, secondary, tertiary, accent
success, danger, warning, info, link

Variant Props

filled, outline

Shape Props

rounded, pill, sharp

Typography Props

sans, serif, mono, semibold, bold

Layout Props

flex, column, itemsCenter, justifyBetween, gap

Override Priority

Understanding how defaults interact with component props:

Priority Order

Component props (highest priority)
ThemeDefaults from closest ThemeProvider
ThemeDefaults from parent ThemeProviders
VaneUI built-in defaults (lowest priority)

function OverrideExample() {
  return (
    <ThemeProvider themeDefaults={{
      button: { primary: true, lg: true }
    }}>
      {/* Uses defaults: primary=true, lg=true */}
      <Button>Default Button</Button>

      {/* Props override defaults: danger=true overrides primary, lg still applies */}
      <Button danger>Danger Button</Button>

      {/* Explicitly disable default: primary=false, lg still applies */}
      <Button primary={false} secondary>Secondary Button</Button>
    </ThemeProvider>
  );
}

Layout Component Defaults

Configure defaults for layout components:

import { ThemeProvider, Container, Section, Card, Stack, Text } from '@vaneui/ui';

function LayoutDefaults() {
  return (
    <ThemeProvider themeDefaults={{
      container: {
        lg: true
      },
      section: {
        secondary: true,
        rounded: true
      },
      card: {
        primary: true,
        rounded: true
      },
      stack: {
        gap: true
      }
    }}>
      <Container>
        <Section>
          <Card>
            <Stack>
              <Text>Content with layout defaults</Text>
            </Stack>
          </Card>
        </Section>
      </Container>
    </ThemeProvider>
  );
}

Dynamic Defaults

Runtime Default Changes

Update defaults based on user preferences or application state:

import { useState } from 'react';
import { ThemeProvider, Button } from '@vaneui/ui';

function DynamicDefaults() {
  const [isCompactMode, setIsCompactMode] = useState(false);

  const themeDefaults = isCompactMode
    ? {
        button: { sm: true },
        card: { sm: true },
        text: { sm: true }
      }
    : {
        button: { lg: true },
        card: { lg: true },
        text: { md: true }
      };

  return (
    <ThemeProvider themeDefaults={themeDefaults}>
      <Button onClick={() => setIsCompactMode(!isCompactMode)}>
        Toggle Compact Mode
      </Button>
    </ThemeProvider>
  );
}

Contextual Defaults

Different defaults for different areas of your app:

import { ThemeProvider } from '@vaneui/ui';

function ContextualDefaults() {
  return (
    <>
      {/* Admin area - compact, subtle styling */}
      <ThemeProvider themeDefaults={{
        button: { sm: true, outline: true, secondary: true }
      }}>
        <AdminPanel />
      </ThemeProvider>

      {/* User area - larger, prominent styling */}
      <ThemeProvider themeDefaults={{
        button: { lg: true, filled: true, primary: true }
      }}>
        <UserInterface />
      </ThemeProvider>
    </>
  );
}

Section-Specific Styling

Different themes for different page sections:

import { ThemeProvider } from '@vaneui/ui';

function MultiSectionApp() {
  return (
    <>
      {/* Hero section - large, bold */}
      <ThemeProvider themeDefaults={{
        button: { xl: true, filled: true },
        title: { xl: true }
      }}>
        <HeroSection />
      </ThemeProvider>

      {/* Content section - medium, subtle */}
      <ThemeProvider themeDefaults={{
        button: { md: true, outline: true },
        text: { sm: true }
      }}>
        <ContentSection />
      </ThemeProvider>

      {/* Footer - compact */}
      <ThemeProvider themeDefaults={{
        button: { xs: true },
        text: { xs: true }
      }}>
        <FooterSection />
      </ThemeProvider>
    </>
  );
}

Best Practices

Consistent Defaults

Establish defaults that align with your design system:

import { ThemeProvider } from '@vaneui/ui';

const designSystemDefaults = {
  // Interactive elements
  button: { primary: true, md: true, filled: true },
  link: { brand: true },

  // Informational elements
  badge: { secondary: true, sm: true },
  chip: { outline: true },

  // Layout elements
  card: { rounded: true },
  section: { gap: true }
};

<ThemeProvider themeDefaults={designSystemDefaults}>
  <App />
</ThemeProvider>

Logical Groupings

Group related defaults together for maintainability:

import { ThemeProvider } from '@vaneui/ui';

const interactiveDefaults = {
  button: { primary: true, filled: true },
  link: { brand: true }
};

const informationalDefaults = {
  badge: { secondary: true, sm: true },
  chip: { outline: true }
};

const layoutDefaults = {
  card: { rounded: true },
  stack: { gap: true }
};

<ThemeProvider themeDefaults={{
  ...interactiveDefaults,
  ...informationalDefaults,
  ...layoutDefaults
}}>
  <App />
</ThemeProvider>

The themeDefaults property provides a robust system for establishing consistent default values throughout your VaneUI application, enabling global consistency while maintaining the flexibility to override defaults when needed.