I'm working on making my app more accessible and am struggling with the MUI Dialog ponent. I'm using the DialogTitle ponent, which creates an H2 element and am getting an issue of "page doesn't contain a level-one heading". Should I be creating my modal in some other way, or are MUI Dialogs just not accessible?

import { Dialog, DialogTitle } from '@mui/material';

const MyModal = () => {

    return (
        <Dialog open={true}>
            <DialogTitle>
                My Title
            </DialogTitle>
        </Dialog>
    );
};

export default MyModal;

I'm working on making my app more accessible and am struggling with the MUI Dialog ponent. I'm using the DialogTitle ponent, which creates an H2 element and am getting an issue of "page doesn't contain a level-one heading". Should I be creating my modal in some other way, or are MUI Dialogs just not accessible?

import { Dialog, DialogTitle } from '@mui/material';

const MyModal = () => {

    return (
        <Dialog open={true}>
            <DialogTitle>
                My Title
            </DialogTitle>
        </Dialog>
    );
};

export default MyModal;

• javascript
• html
• reactjs
• material-ui
• accessibility

• @steve's solution sounds good but if it doesn't work, don't worry about the dialog heading being an <h2> instead of an <h1>. As long as it's the "smallest" heading level in your dialog (if you happen to have other headings in the dialog), then you're ok from an accessibility perspective. There's nothing that says you must have an <h1>. Whatever scanning tool you're using that generates that "error" is purely subjective on the scanning tool coder's opinion. There is nothing in WCAG that says you must have an <h1>. – slugolicious Commented Dec 23, 2021 at 18:38

3 Answers 3

Updated for MUI v5:

The Dialog ponent API includes a helper DialogTitle ponent which, by default, renders its contents within an h2 element. To change this functionality, you can pass the ponent property to the DialogTitle to have the DialogTitle rendered using whatever elementType that you wish. For example:

<DialogTitle ponent="h1">
  My Dialog Title
</DialogTitle>

This is currently an undocumented feature of DialogTitle, but it can been seen in the source code that properties that are passed to DialogTitle are spread onto the underlying Typography ponent -- By passing ponent, you are essentially overwriting the hardcoded ponent="h2" prop with your own value.

Working example: https://codesandbox.io/s/simpledialog-material-demo-forked-kpq9k?file=/demo.js

Original answer for MUI v4:

The Dialog ponent API includes a helper DialogTitle ponent which, by default, renders its contents within an h2 element. To disable this functionality, you can use the DialogTitle ponent with the disableTypography prop (to disable the h2 wrapping behavior) and then include your own Typography ponent set to h1. For example:

<DialogTitle disableTypography>
  <Typography variant="h1">My Dialog Title</Typography>
</DialogTitle>

Working example: https://codesandbox.io/s/material-demo-forked-7pso2?file=/demo.js

Extra Credit: You may then e across the problem that the h1 is styled "too large" for your design. If so, and you prefer the h2 look, you can use the Typography prop named ponent in bination with the variant prop to visually style it back to an h2, while maintaining the underlying h1 element. For example:

<DialogTitle disableTypography>
  <Typography variant="h2" ponent="h1">My Dialog Title</Typography>
</DialogTitle>

In the case of TypeScript there's no typing provided so you need to do a hack:

<DialogTitle {...{ ponent: 'div' } as any}>
  <Typography variant="h1">My Dialog Title</Typography>
</DialogTitle>

This is a temporary hack until they add the typing for all the props there.

As @Steve mentionned, in Mui v5, the job is harder. Even if you specify a ponent prop (which won't work in TS, moreover it's a bad practice), it won't change the style as it renders a h2 with a h6-style.

The cleanest workaround would be to mess with CSS (in a styled ponent for eg)

// Styling
import { styled } from "@mui/system";

// UI
import { DialogTitle as MuiDialogTitle } from "@mui/material";


const DialogTitle = styled(MuiDialogTitle)(({ theme }) => ({
  "&.MuiDialogTitle-root.MuiTypography-root": {
    fontSize: 25,
    fontWeight: "bold",
  },
}));