Why your video doesn't autoplay — 3 causes, including React's muted bug

You put a background video on your homepage. On your laptop in Chrome it plays. You open it on an iPhone — the first frame just sits there with a grey "play" triangle in the middle.
The annoying part: your code is exactly what the tutorials say. autoPlay is there, muted is there. But if the site is built with React or Next.js, it may well turn out that muted never reached the browser. It's an old React quirk, more on it below.
Let's start with the most common cause. Each one follows the same pattern: cause → how to check → how to fix.
Cause 1. The video has sound (most common)
Browsers don't let sites make noise out of nowhere. The rule is similar everywhere:
- a video without sound (
muted) may always start on its own; - a video with sound — only after the user has clicked something on the page.
There's also a "works for me" trap. Chrome remembers sites where you often start videos yourself. It lets those sites autoplay with sound. You click videos on your own site dozens of times — and Chrome trusts you. A new visitor sees a frozen frame.
How to check. Open the console. In Chrome you'll see an error like:
play() failed because the user didn't interact with the document first
Even more reliable: open the site in an incognito window. There the browser has no trust history — just like your users.
How to fix. Add muted. If sound really matters, start muted and show an "Unmute" button. Turning sound on after a tap is always allowed.
Cause 2. No playsinline on iPhone
Safari on iPhone has historically shown video full screen. Without a special attribute it won't play a clip inside the page — so there's no autoplay either. It's one of those small things that's why you should check your site on an actual phone.
How to check. Look at the tag: is playsinline there? In React the attribute is written playsInline, with a capital I.
How to fix. The full set for a background video:
<video autoplay muted loop playsinline poster="/hero.jpg">
<source src="/hero.mp4" type="video/mp4" />
</video>
poster is the image people see while the video loads, or if it never starts. Don't skip it.
Cause 3. React drops the muted attribute
Here's the non-obvious one. You write muted in JSX, but React sets it as an element property, not as an attribute in the HTML. It's a known story: the issue has been open in the React repo since 2017.
While everything renders in the browser, there's barely a difference. But if the page is rendered on the server, as in Next.js, the HTML arrives with a tag without muted. Safari looks at that HTML, sees "a video with sound" and blocks autoplay. React mutes it later, after the decision has already been made.
How to check. On the page, run this in the console:
document.querySelector("video").outerHTML
If the output has no muted, but your JSX does — that's it.
How to fix. Set muted by hand through a ref and start the video yourself:
const ref = useRef(null)
useEffect(() => {
const video = ref.current
video.muted = true
video.play().catch(() => {})
}, [])
return <video ref={ref} autoPlay muted loop playsInline poster="/hero.jpg" src="/hero.mp4" />
play() returns a promise. If the browser still refuses, the error won't hang red in the console, and the user sees the poster.
Bonus: sometimes the user turned it off
On iPhone in Low Power Mode, Safari often won't autoplay video. In Safari and Chrome site settings, users can switch autoplay off entirely. Nothing is broken here and there's nothing to fix. That's why a video should always have a poster, and the page's meaning shouldn't depend on the clip.
Same logic as with images that don't load: always think about what a person sees if the media never shows up.
How to ask AI to fix it right away
the video doesn't play on iphoneThe homepage background video does not autoplay on iPhone in Safari, it works in Chrome on a laptop. The project is Next.js. Check that the video tag has muted, playsInline, loop and poster. Keep in mind that React does not output the muted attribute in server HTML: set video.muted = true through a ref and call play() with catch. If the video fails to start, the poster must stay visible.Why does it work for me but not for my users?
Most likely Chrome trusts you as a frequent viewer of your own site. Test autoplay in an incognito window and on a real phone — that way you see the site through a new visitor's eyes.
Can I autoplay with sound?
Only after a user action. For example, the video starts muted, and when a button is tapped you set video.muted = false. There's no way around this rule.
Wouldn't a GIF be simpler?
No. A GIF weighs many times more than a short MP4 and looks worse. A silent video with muted and playsinline starts just as reliably as a GIF, but loads faster.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





