Theming

CSS Variables

Astra UI components use CSS variables for theming. You can override these variables to customize the appearance of all components:

:root {
  --astra-font-family: 'Your Custom Font', sans-serif;
  --astra-neutral-100: #f5f5f5;
  --astra-neutral-200: #e5e5e5;
  --astra-neutral-500: #737373;
  --astra-neutral-700: #404040;
  --astra-neutral-800: #262626;
  --astra-neutral-900: #171717;
  --astra-accent: #3b82f6;
  --astra-red-600: #dc2626;
  --astra-red-700: #b91c1c;
  --astra-red-800: #991b1b;
  --astra-red-900: #7f1d1d;
}

Understanding Shadow DOM

Astra UI components use Shadow DOM, which encapsulates the component's HTML structure and styles. This encapsulation means that:

• Styles defined outside the component won't affect its internal elements
• Styles defined inside the component won't leak out and affect other elements on the page

To style elements within the Shadow DOM, we use the ::part() pseudo-element:

/* This won't work due to Shadow DOM encapsulation */
astra-button {
  background-color: red;
}

/* This will work, using ::part() */
astra-button::part(button) {
  background-color: red;
}

Customizing Components

Each component can be customized individually using CSS. Here are examples for some core components:

/* Customizing button styles */
astra-button::part(button) {
  background: var(--astra-neutral-700);
  color: white;
  border-radius: 8px;
}

/* Dark mode customization */
@media (prefers-color-scheme: dark) {
  astra-button::part(button) {
    background: var(--astra-neutral-200);
    color: black;
  }
}

/* Customizing input styles */
astra-input::part(input) {
  border: 1px solid var(--astra-neutral-200);
  background: var(--astra-neutral-100);
  color: var(--astra-neutral-900);
}

/* Dark mode customization */
@media (prefers-color-scheme: dark) {
  astra-input::part(input) {
    border: 1px solid var(--astra-neutral-800);
    background: var(--astra-neutral-900);
    color: var(--astra-neutral-100);
  }
}

/* Customizing text styles */
astra-text[variant="h1"] {
  font-size: 36px;
  line-height: 40px;
  font-weight: 600;
  color: var(--astra-neutral-900);
}

/* Dark mode customization */
@media (prefers-color-scheme: dark) {
  astra-text[variant="h1"] {
    color: var(--astra-neutral-100);
  }
}

Dark Mode

Astra UI components support dark mode out of the box. They use the prefers-color-scheme media query to detect the user's preference. You can override this behavior or provide your own dark mode styles as shown in the examples above.

Best Practices

• Use CSS variables for global theming to ensure consistency across components.
• Customize individual components using the ::part() pseudo-element for more granular control.
• Consider both light and dark modes when customizing components.
• Test your customizations across different browsers and devices to ensure consistency.

Advanced Styling

For more complex styling needs, you can use CSS custom properties (variables) defined within the components. These variables are exposed to the light DOM and can be overridden:

astra-button {
  --astra-button-background: #4a90e2;
  --astra-button-color: white;
}
      

Check each component's documentation for a list of available CSS custom properties.