Angular: how to embed responsive YouTube videos
This tutorial explains the steps required to add YouTube videos without breaking your design and while keeping the page responsive.
1. Install the @angular/youtube-player package
Install the youtube-player package with the following npm command:
2. Import the library
In a current standalone component, import YouTubePlayer directly in the component imports array. YouTubePlayerModule remains useful for older NgModule-based applications.
3. Add the YouTube Player component to the HTML
After the first two steps, you can add the YouTube player component to your target template using the video ID. The ID appears in the URL, as shown in the following example.
Example:
If we take the video "Implementación de una API en Python para enviar email con Angular", the ID after ?v= is RSGQuH_gWNw.
The sample code for the URL https://www.youtube.com/watch?v=RSGQuH_gWNw would be:
Details of the remaining parameters
If you are interested, the library provides the following parameters:- videoId: text. The ID of the YouTube video we want to show.
- height: number. Height of the video player.
- width: number. Width of the video player.
- startSeconds: number. Moment when we want the player to start playing.
- endSeconds: number. Moment when we want the player to stop playing. The number matches the second where playback will end.
- suggestedQuality: suggested quality in the player. The available values are default, small, medium, large, hd720, hd1080 and highres.
- showBeforeIframeApiLoads: boolean. The iframe will try to load regardless of the API state on the page. Set this to true if you do not want onYouTubeIframeAPIReady to be defined on the global window object.
4. API loading, placeholder and privacy mode
With the current package, you do not need to place the YouTube iframe API script manually in index.html. The component loads it when needed, keeps a lightweight placeholder initially and can switch the player host to youtube-nocookie.com with disableCookies.
5. Responsive design
The player still needs dimensions that follow its container. A ResizeObserver reacts to the component width without attaching a global resize listener and can be disconnected cleanly:
And add the following markup to the view.
6. Result
7. Performance and SEO notes
Embedding a YouTube player adds an external iframe, network requests and JavaScript outside your Angular bundle. That is acceptable for a tutorial page, but on content-heavy pages it is better to lazy load the player only when the video is close to the viewport.
For SEO, keep the explanation in normal HTML before the iframe. Google can understand the surrounding text, headings and code examples even when the video itself is hosted externally.
Lazy loading strategy
If the page contains several videos, the best pattern is to render a lightweight placeholder first and create the real player only after the user clicks or when the block approaches the viewport. This avoids loading the YouTube iframe API for visitors who only read the article and never play the video.
The placeholder should keep the same aspect ratio as the final player, include an accessible button label and show enough context in surrounding text. That way the page remains stable, readable and indexable while the heavier media element is delayed.
When a plain iframe is the better option
Use the Angular component when you need playback events, programmatic controls, playlists or state synchronization. For a documentation page that only needs one playable video, a direct iframe is simpler, has fewer moving parts and can be made responsive entirely with CSS.
Accessibility and resilient playback
Give every iframe or placeholder a specific accessible name, keep keyboard focus visible and do not start audio automatically. Add a normal link to the video and a short textual summary so the content still works when the video is private, embedding is disabled, a content blocker stops the request or the user cannot play media.
If the application controls playback through the IFrame API, provide the page origin and handle player errors such as unavailable videos or embeds disabled by the owner. Autoplay must be treated as optional because browsers can block it until the user interacts.
Production test matrix
- SSR response contains the heading, explanation and fallback link before hydration.
- The container keeps a 16:9 ratio on narrow mobile and wide desktop screens.
- Keyboard users can reach and activate the placeholder without losing focus.
- The page remains readable with third-party scripts blocked and on a slow network.
- Consent and Content Security Policy rules allow only the domains the chosen embed actually needs.
Official references
Common implementation mistakes
The most common mistake is mixing fixed width and responsive containers. A player with width 500 can look fine on desktop and overflow on a mobile viewport. Another frequent issue is initializing the player before the container has a measurable width, which produces incorrect dimensions until the next resize event.
For production, test the component in SSR, mobile, slow network and privacy-focused browsers. Some users block third-party media scripts, so the article should still make sense when the iframe cannot load.
Privacy and consent
YouTube embeds can set third-party cookies or trigger external requests depending on configuration and region. If the page is privacy-sensitive, use the nocookie domain, delay the iframe until interaction and explain that the video is hosted by an external provider.
Implementation checklist
- Use a reusable wrapper component instead of duplicating iframe markup.
- Keep a stable aspect ratio so the layout does not jump while loading.
- Add a visible title or paragraph explaining what the video covers.
- Avoid fixed pixel widths on mobile views.
- Prefer lazy loading when several videos appear on the same article.