New 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



  "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.


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


Used to represent potentially dangerous actions or important messages.


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


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


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

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


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 indicates border radius base for styling system.

  "shape": {
    "borderRadius": 0


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.


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


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"


  "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


// 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;


import {
} 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"];