Themes and Styling in MDCGrid

The MDCGrid provides extensive theming capabilities to allow developers to customize the look and feel of the grid. The theming system is designed to be flexible, enabling customization of various grid elements such as the general layout, cells, header cells, dimension tabs, and icons.

The MDCGrid supports two main themes: light and dark. By default, the grid uses the light theme, but you can switch to the dark theme or apply custom themes using the provided methods.

This document provides a comprehensive guide to configuring and applying themes, including details on how to manage and customize theme settings.

QuickStart

Base Theme

The base theme can be set using the setTheme method. This method accepts "light" or "dark" as its argument. If no argument is provided, the "light" theme is used by default.

Syntax:

grid.setTheme("dark");

Custom Theme Configuration

After applying a base theme, you can customize specific aspects of the grid by using the setThemeConfig method. This method allows you to pass an IGridThemeConfig object, specifying overrides for default theme properties.

Syntax:

const customThemeConfig: IGridThemeConfig = {
  general: {
    backgroundColor: "#1e1e1e",
    accentColor: "#ff4081",
  },
  cells: {
    textColor: "#ffffff",
  },
};

grid.setThemeConfig(customThemeConfig);

In the example above, only backgroundColor, accentColor, and textColor are overridden. The rest of the theme will follow the default settings of the base theme (“dark” in this case).

Theme Configuration Interface

Grid Theme Type (`IGridTheme`)

The IGridTheme type represents the base theme options available for the grid.

Options:

"dark": Applies a dark color scheme to the grid.
"light": Applies a light color scheme to the grid.

Grid Theme Configuration Interface (`IGridThemeConfig`)

The IGridThemeConfig interface defines the complete theme configuration for the grid. It consists of partial configurations for different theme components, allowing customization of specific parts of the theme.

Properties:

general (Partial<IGridThemeGeneral>): Customizes the general appearance of the grid, including properties like background color, font settings, and border styles.
cells (Partial<IGridThemeCells>): Customizes the appearance of grid cells, including text color, background color, and padding.
dimensionsTabs (Partial<IGridThemeDimensionsTabs>): Customizes dimension tabs, including text color, background color, font size, font family, and font weight.
headerCells (Partial<IGridThemeHeaderCells>): Customizes header cells, including text color, background color, font size, and font weight.
icons (Partial<IGridThemeIcons>): Customizes icon sizes used within the grid.

Grid Theme General Interface (`IGridThemeGeneral`)

The IGridThemeGeneral interface defines fundamental styling aspects for the grid.

Properties:

backgroundColor (string): The background color of the grid.
fontFamily (string): The font family used throughout the grid.
fontSize (number): The base font size for text in the grid.
fontWeight (number): The font weight used for text.
foregroundColor (string): The color used for foreground text or elements.
accentColor (string): The color used for accent elements.
border (number): The border width for grid elements.
borderColor (string): The color of the border.
gutter (number): The space between grid elements.
wrapperRadius (number): The border-radius for the grid wrapper.
widgetRadius (number): The border-radius for individual grid widgets.
error (string): The color used to indicate errors.
onError (string): The color used for text or elements on an error background.
success (string): The color used to indicate success.
onSuccess (string): The color used for text or elements on a success background.
disabled (string): The color used for disabled elements.
padding (number): The padding around grid elements.

Grid Theme Cells Interface (`IGridThemeCells`)

The IGridThemeCells interface defines the appearance of individual grid cells.

Properties:

textColor (string): The color of the text inside grid cells.
backgroundColor (string): The background color of grid cells.
padding (number): The padding inside grid cells.

Grid Theme Dimensions Tabs Interface (`IGridThemeDimensionsTabs`)

The IGridThemeDimensionsTabs interface customizes the appearance of dimension tabs.

Properties:

textColor (string): The color of the text on dimension tabs.
backgroundColor (string): The background color of dimension tabs.
fontSize (number): The font size used on dimension tabs.
fontFamily (string): The font family used for dimension tabs.
fontWeight (number): The font weight used on dimension tabs.

Grid Theme Header Cells Interface (`IGridThemeHeaderCells`)

The IGridThemeHeaderCells interface defines the appearance of header cells.

Properties:

textColor (string): The color of the text in header cells.
backgroundColor (string): The background color of header cells.
fontSize (number): The font size used in header cells.
fontWeight (number): The font weight used in header cells.

Grid Theme Icons Interface (`IGridThemeIcons`)

The IGridThemeIcons interface defines the size of icons used within the grid.

Properties:

size (number): The size of icons in the grid.

By configuring these interfaces and types, you can customize the appearance of the grid to match your design requirements.

Applying Themes to the Grid

Applying themes customizes the grid’s appearance. This section describes how to apply themes using the MDCGrid class and its associated methods.

Using the `setTheme` Method

The setTheme method applies a base theme to the grid. The base theme can be either "dark" or "light".

Syntax:

grid.setTheme(theme: IGridTheme): void;

Parameters:

theme (IGridTheme): The base theme to apply. It can be either “dark” or “light”. If no theme is provided, “light” is used by default.

Example:

const grid = new MDCGrid();
grid.setTheme("dark");  // Applies the dark theme to the grid

Using the `setThemeConfig` Method

The setThemeConfig method applies a custom theme configuration by specifying detailed properties for various grid components.

Syntax:

grid.setThemeConfig(config: IGridThemeConfig): void;

Parameters:

config (IGridThemeConfig): The theme configuration object. You can provide a complete configuration or only the parts you want to customize.

Example:

const themeConfig: IGridThemeConfig = {
    general: {
        backgroundColor: "#FFFFFF",
        fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
        foregroundColor: "#2A2A2A",
        accentColor: "#4285F4",
        border: 1,
        borderColor: "#DFDFDF",
        gutter: 4,
        fontSize: 16,
        fontWeight: 400,
        wrapperRadius: 6,
        widgetRadius: 6,
        error: "#F80000",
        onError: "#E8E8E8",
        success: "#4E9F03",
        onSuccess: "#E8E8E8",
        disabled: "#D0D0D0",
        padding: 12
    },
    cells: {
        textColor: "#4A4A4A",
        backgroundColor: "#E8E8E8",
        padding: 3
    },
    dimensionsTabs: {
        textColor: "#E8E8E8",
        backgroundColor: "#2A2A2A",
        fontSize: 16,
        fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
        fontWeight: 500
    },
    headerCells: {
        textColor: "#4A4A4A",
        backgroundColor: "#b3b3b3",
        fontSize: 16,
        fontWeight: 400
    },
    icons: {
        size: 24
    }
};

grid.setThemeConfig(themeConfig);  // Applies the custom theme configuration to the grid

Combining `setTheme` and `setThemeConfig`

You can use both methods to first set a base theme and then apply additional customizations. This allows you to start with a default theme and make specific adjustments as needed.

Default Theme

The grid package includes built-in default themes that provide a polished and consistent look. These default themes are available in both light and dark modes.

Default Light Theme

The default light theme is designed for a clean and modern appearance with subtle accents.

Configuration:

{
    general: {
        backgroundColor: "#FFFFFF",
        fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
        foregroundColor: "#2A2A2A",
        accentColor: "#4285F4",
        border: 1,
        borderColor: "#DFDFDF",
        gutter: 4,
        fontSize: 16,
        fontWeight: 400,
        wrapperRadius: 6,
        widgetRadius: 6,
        error: "#F80000",
        onError: "#E8E8E8",
        success: "#4E9F03",
        onSuccess: "#E8E8E8",
        disabled: "#D0D0D0",
        padding: 12
    },
    cells: {
        textColor: "#4A4A4A",
        backgroundColor: "#E8E8E8",
        padding: 3
    },
    dimensionsTabs: {
        textColor: "#E8E8E8",
        backgroundColor: "#2A2A2A",
        fontSize: 16,
        fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
        fontWeight: 500
    },
    headerCells: {
        textColor: "#4A4A4A",
        backgroundColor: "#b3b3b3",
        fontSize: 16,
        fontWeight: 400
    },
    icons: {
        size: 24
    }
}

Default Dark Theme

The default dark theme provides a high-contrast palette suitable for low-light environments.

Configuration:

{
    general: {
        backgroundColor: "#27374D",
        fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
        foregroundColor: "#DDE6ED",
        accentColor: "#BB86FC",
        border: 1,
        borderColor: "#03DAC6",
        gutter: 4,
        fontSize: 16,
        fontWeight: 400,
        wrapperRadius: 6,
        widgetRadius: 6,
        error: "#F52F2F",
        onError: "#FFFFFF",
        success: "#34A853",
        onSuccess: "#FFFFFF",
        disabled: "#E8E8E8",
        padding: 12
    },
    cells: {
        textColor: "#DDE6ED",
        backgroundColor: "#50727B",
        padding: 3
    },
    dimensionsTabs: {
        textColor: "#DDE6ED",
        backgroundColor: "#526D82",
        fontSize: 16,
        fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
        fontWeight: 500
    },
    headerCells: {
        textColor: "#DDE6ED",
        backgroundColor: "#344955",
        fontSize: 16,
        fontWeight: 400
    },
    icons: {
        size: 24
    }
}

The default light theme is automatically applied if no custom theme is provided.

Themes and Styling in MDCGrid

QuickStart

Base Theme

Custom Theme Configuration

Theme Configuration Interface

Grid Theme Type (IGridTheme)

Grid Theme Configuration Interface (IGridThemeConfig)

Grid Theme General Interface (IGridThemeGeneral)

Grid Theme Cells Interface (IGridThemeCells)

Grid Theme Dimensions Tabs Interface (IGridThemeDimensionsTabs)

Grid Theme Header Cells Interface (IGridThemeHeaderCells)

Grid Theme Icons Interface (IGridThemeIcons)

Applying Themes to the Grid

Using the setTheme Method

Using the setThemeConfig Method

Combining setTheme and setThemeConfig

Default Theme

Default Light Theme

Default Dark Theme

Grid Theme Type (`IGridTheme`)

Grid Theme Configuration Interface (`IGridThemeConfig`)

Grid Theme General Interface (`IGridThemeGeneral`)

Grid Theme Cells Interface (`IGridThemeCells`)

Grid Theme Dimensions Tabs Interface (`IGridThemeDimensionsTabs`)

Grid Theme Header Cells Interface (`IGridThemeHeaderCells`)

Grid Theme Icons Interface (`IGridThemeIcons`)

Using the `setTheme` Method

Using the `setThemeConfig` Method

Combining `setTheme` and `setThemeConfig`