[docs][material-ui][Card] CardMedia description is wrong

[arigoldx]

Related page

https://mui.com/material-ui/react-card/

Kind of issue

Unclear explanations

Issue description

The text for Card Media states:

Card Media: an optional container for displaying background images and gradient layers behind the Card Content.

but I cannot figure out how to make a background image using CardMedia. The image displays above the CardContent. CardMedia is not meant to be used as a background for the Card and it's description in the docs should be updated.

Context

Simply put, I'd like to add a background image for the card. Something like this (which I found on the web after searching for "login screen with background image"):

Search keywords: card, media, background image

[arigoldx]

Fwiw, I found a solution to adding a background image on a Card.

Again, this presumes that the "right" / "mui best practices" way to code a login page (as per the image above) with a background image is using a Card. Seems like something called "CardMedia" would be.

First you use require to get the image:

const heroImage = require('../../assets/images/hero-images/cool-image.jpg');

then you use the sx property on Card using backticks and the url css function:

<Card sx={{backgroundImage: `url(${heroImage})` }}>

I'm admittedly still learning the best way to get images when using webpack (which, I've learned, is bundled with create-react-app). Maybe it's an import? Maybe it's a require? Would love articles to read on that if you have 🙇.

[ZeeshanTamboli]

You can check the demo examples for adding images with the Card Media component. Regarding the text about gradient layers behind the Card Content:

and gradient layers behind the Card Content

I agree it's confusing since the image is above the card content. This was added in #40346. Maybe @anle9650 can explain it better since he added it. I'll mark it as a bug for now.

[arigoldx]

You can check the demo examples for adding images with the Card Media component.

I think I already did but I couldn't find any examples of background images. In the examples, the images are never behind the content.

Tho maybe I missed something? 🤔

[ZeeshanTamboli]

First, seeing your login page image above, I'm curious why you're using the Card component for your login page unless it's a separate container.

What you're looking for is similar to the Card Cover component from Joy UI, which isn't available in Material UI. I also saw now that the description text for Card Media was copied from the Joy UI Card Cover: https://mui.com/joy-ui/react-card/#introduction.

So, this is definitely a bug in the Material UI Card Media description text. For your use case of having card content above a background image, could you create a new issue so we can track it as a new feature?