[AppBar] Default `elevation` and `square` props are incorrectly documented

[thany]

Steps to reproduce

Steps:

1. Open this link to live example: https://stackblitz.com/run?file=src%2FDemo.tsx
2. Inspect the <header> element
3. Observe the elevation class

Current behavior

The default elevation is actually 4, while in intellisense it says the default is 1. This may lead to confusion.

Furthermore, in the documentation for AppBar, it doesn't mention the elevation prop at all, but instead refers to the documentation for Paper, where the default of 1 is mentioned.

The one for Paper is probably correct (not tested), but it's different for AppBar so it makes sense to at least mention it.

Expected behavior

So generally speaking, when a prop is inherited but not its default value, it should be re-mentioned in the documentation, and it should display the true default value in intellisense.

Context

I have a scenario where I wanted to set the elevation to 1, and thought to myself "why am I doing that, that's supposed to be the default". Only to discover it's not actually the default. So for me it lead to confusion.

It could also lead to confusion when it looks better to put the (supposed) default value explicitly in a scenario like this:

elevation={defaultElevation ? 1 : 5}

Where defaultElevation is a prop or some arbitrary condition. This to me looks weird:

elevation={defaultElevation ? undefined : 5}

Even though it would work perfectly fine.

And to re-iterate, I'm sure elevation isn't the only prop with a problem like this. There are quite possibly other props that I haven't encountered yet, that are inherited from a base component, but have a different default value.

Your environment

npx @mui/envinfo

  System:
    OS: Windows 10 10.0.19045
  Binaries:
    Node: 22.21.0 - C:\Program Files\nodejs\node.EXE
    npm: 11.6.2 - C:\Program Files\nodejs\npm.CMD
    pnpm: Not Found
  Browsers:
    Chrome: 142.0.7444.163
    Edge: Chromium (141.0.3537.99)
    Firefox: 145.0 - C:\Program Files\Mozilla Firefox\firefox.exe
  npmPackages:
    @emotion/react:  11.14.0
    @emotion/styled: ^11.14.1 => 11.14.1
    @mui/core-downloads-tracker:  7.3.2
    @mui/icons-material:  7.3.2
    @mui/lab:  7.0.0-beta.17
    @mui/material: ^7.3.1 => 7.3.2
    @mui/material-nextjs:  7.3.2
    @mui/private-theming:  6.4.9
    @mui/styled-engine:  7.3.2
    @mui/styles: ^6.4.8 => 6.5.0
    @mui/system:  7.3.2
    @mui/types:  7.4.6
    @mui/utils:  7.3.2
    @mui/x-date-pickers: ^8.11.2 => 8.11.2
    @mui/x-internals:  8.11.2
    @types/react: ^19.0.1 => 19.1.12
    react:  19.1.1
    react-dom:  19.1.1
    typescript:  5.9.2

I'm using Firefox. Not that it matters.

Search keywords: AppBar default elevation

[ZeeshanTamboli]

Your StackBlitz reproduction has incorrect link. However, I understood the issue.

The square prop also has a different default value i.e of true compared to square in Paper.

What we can do is define it separately for AppBar in TS type definitions and omit it from Paper which we extend in AppBar types. The docs are generated from this type.

We can do:

--- a/packages/mui-material/src/AppBar/AppBar.d.ts
+++ b/packages/mui-material/src/AppBar/AppBar.d.ts
@@ -23,6 +23,12 @@ export interface AppBarOwnProps {
     PropTypes.Color | 'transparent' | 'error' | 'info' | 'success' | 'warning',
     AppBarPropsColorOverrides
   >;
+  /**
+   * Shadow depth, corresponds to `dp` in the spec.
+   * It accepts values between 0 and 24 inclusive.
+   * @default 4
+   */
+  elevation?: number;
   /**
    * If true, the `color` prop is applied in dark mode.
    * @default false
@@ -35,6 +41,11 @@ export interface AppBarOwnProps {
    * @default 'fixed'
    */
   position?: 'fixed' | 'absolute' | 'sticky' | 'static' | 'relative';
+  /**
+   * If `false`, rounded corners are enabled.
+   * @default true
+   */
+  square?: boolean;
   /**
    * The system prop that allows defining system overrides as well as additional CSS styles.
    */
@@ -49,7 +60,7 @@ export type AppBarTypeMap<
     props: AdditionalProps & AppBarOwnProps;
     defaultComponent: RootComponent;
   },
-  'position' | 'color' | 'classes'
+  'position' | 'color' | 'classes' | 'elevation' | 'square'
 >;

 /**

Anone picking this up, also make sure to run pnpm proptypes and pnpm docs:api respectively to generate proptypes and the API docs.

[mj12albert]

Also: anybody interested in working on this please go ahead and directly open a PR, be sure to link the PR to this issue ~

[Ad1tya-007]

Hi, I raised a PR for this! #47261