Theme

MetaFox theme is based on Material UI (opens in a new tab), a beautiful design and features with a suite of customization options that make it easy to implement your own custom design system.

MetaFox theme defines styles and layouts, in which styles indicate color palette, typography

Create A New Theme

Install dependencies

Open terminal and navigate to frontend project root folder. Then run the command

yarn && yarn bootstrap

Using metafox-cli tool to create a new theme and install to frontend workbox.

npx metafox-cli

Example to create new theme chocolate and associate package @foxtheme/chocolate.

✔ What do you need? · Create new app
✔ What is vendor/company name? · foxdev
✔ What is theme id? · chocolate
Generating theme files ...
Updating workspace ...
Reloading workspace ...
Generated theme chocolate located at ./packages/foxdev/theme-chocolate
Restart frontend terminal to apply changes.

Now, you can see that the new theme files are generated under packages/foxdev/theme-chocolate folder Restart frontend terminal then refresh the browser to see changes.

Customize Styling

Styling is defined in packages/foxdev/theme-chocolate/src/styles.json, includes

palette - used to modify colors
typography - used to modify CSS font properties
shape - used to modify border radius system

Palette

palette.primary

{
  "primary": {
    "main": "#2682d5",
    "light": "#4a97dc",
    "dark": "#0a71cd"
  }
}

Used to represent primary interface elements for a user. Modifying palette primary will affect to submit buttons, continue buttons, upload file button, links, selected menu items.

palette.error

Used to represent interface elements that the user should be made aware of. Modifying palette error will affect to error messages

palette.warning

Used to represent potentially dangerous actions or important messages.

palette.success

Used to indicate the successful completion of an action that user triggered.

palette.border

palette.border - border color of components
palette.divider - used to present color of divider component.

palette.background

{
  background: {
    default: "#ededed",
    paper: "#fff",
    auto: "transparent",
  },
}

background.default Used to present background of your site & paper.

Typography

Typography indicates CSS font properties. Typography supported variant h1, h2, h3, h4, h5, h6, subtitle1, subtitle2, body1, body2, button, caption, overline. The following code styling for typography h1.

{
  "h1": {
    "fontWeight": 700,
    "fontSize": "40px",
    "lineHeight": 1.2,
    "letterSpacing": "0"
  }
}

Shape

Shape indicates border radius base for styling system.

{
  "shape": {
    "borderRadius": 0
  }
}

LayoutSlot

Layout slots define sizes for layout slot.

{
  "layoutSlot": {
    "background": {
      "paper": "#f5f5f5"
    },
    "points": {
      "xs1": 306,
      "xs2": 322,
      "xs3": 400,
      "xs": 400,
      "sm1": 600,
      "sm": 720,
      "md": 1024,
      "lg": 1200,
      "xl": 1920
    }
  }
}

Custom Components

MetaFox theme system allows to overrides Material components by processors.

Components.ts

In order to customize themed components (opens in a new tab). Edit the src/processors/Component.ts file

The following example explain how to customize button styles (opens in a new tab)

import { Theme, ThemedProps } from "@mui/material";
 
export default function overridesComponents(theme: Theme): void {
  theme.components.MuiButton = {
    defaultProps: {
      variant: "contained",
    },
    styleOverrides: {
      root: {
        borderRadius: 4,
        textTransform: "none",
        boxShadow: "none",
      },
    },
  };
  // other components
}

CssBaseLine.ts

In order to overrides css baseline (opens in a new tab), edit the processors/CssBaseLine.ts file

import { Theme } from "@mui/material";
 
export default function overridesGlobalStyles(theme: Theme) {
  if (!theme.components) {
    theme.components = {};
  }
 
  theme.components.MuiCssBaseline = {
    styleOverrides: {
      html: {
        WebkitFontSmoothing: "auto",
        fontSize: "16px",
      },
      body: {
        fontFamily: theme.fontFamily,
        overflowX: "hidden",
      },
      a: {
        color: theme.palette.primary.main,
      },
    },
  };
}

Custom Site Blocks

Site blocks allow to add blocks to any templates, on certain screen size and slot name in layout. You can put blocks to all templates in the layout.siteBlocks.origin.json file as below

{
  [screenSize]: [
    {
      "blockId": [global unique id],
      "component": [componentName],
      "slotName": [slotName],
      "blockOrigin": "site",
      "blockLayout": "none"
    }
  ]
}

Example

{
  "small": [
    {
      "blockId": "appbar0",
      "component": "core.siteBarMobileBlock",
      "slotName": "header",
      "blockOrigin": "site",
      "blockLayout": "none"
    }
  ],
  "large": [
    {
      "blockOrder": -1,
      "component": "core.block.appbar",
      "slotName": "header",
      "blockId": "appbar0",
      "blockOrigin": "site",
      "blockLayout": "none"
    }
  ]
}

Theme Backend

In order to allow site administrator control theme, MetaFox theme system requires a Backend PHP package associated with the theme. Go to AdminCP, access /admincp/layout/theme/create

Create Theme

Export Theme

Follow Export MetaFox package to export theme.

Custom Styles

Define

// TruncateText.tsx
export interface TruncateTextProps extends TypographyProps {
  component?: React.ElementType;
  lines?: 0 | 1 | 2 | 3 | 4 | 5;
  fontWeight?: number;
  fixHeight?: boolean;
  showFull?: boolean;
  isIE?: boolean;
}
 
const TruncateText = styled(Box, {
  name: "MuiTruncateText",
  slot: "Root",
  shouldForwardProp(prop: string) {
    return prop !== "lines" && prop !== "fixHeight" && prop !== "showFull";
  },
})<TruncateTextProps>(({ theme }) => ({
  display: "block",
  maxWidth: "100%",
}));
 
export default TruncateText;

Typings

import {
  ComponentsOverrides,
  ComponentsProps,
  ComponentsVariants,
} from "@mui/material/styles";
import "@mui/material/styles/components";
 
declare module "@mui/material/styles/components" {
  interface Components {
    MuiTruncateText?: {
      defaultProps?: ComponentsProps["MuiTruncateText"];
    };
    MuiItemView?: {
      defaultProps?: ComponentsProps["MuiItemView"];
      styleOverrides?: ComponentsOverrides["MuiItemView"];
      variants?: ComponentsVariants["MuiItemView"];
    };
  }
}

New App New Language