fluidvids.js is a lightweight JavaScript library designed to make responsive video embedding effortless. It intelligently handles various video embed codes (YouTube, Vimeo, Wistia, etc.) ensuring they scale proportionally with their container, maintaining aspect ratio and preventing distorted video playback on different screen sizes and devices. Unlike CSS-only solutions, fluidvids.js gracefully handles edge cases and inconsistencies across different browsers and embed providers, offering a robust and reliable solution for responsive video integration.
There are two primary ways to install and include fluidvids.js in your project:
1. Download and Include (Direct Method):
fluidvids.js file from https://github.com/toddmotto/fluidvids.fluidvids.js file in your project’s JavaScript directory.<head> or just before the closing </body> tag:<script src="path/to/fluidvids.js"></script>Replace "path/to/fluidvids.js" with the actual path to the downloaded file. Fluidvids.js will automatically find and process video embeds on the page.
2. Using a Content Delivery Network (CDN):
For quicker integration, you can use a CDN. While this is less reliable for control over versions, it’s often simpler:
<script src="https://cdn.jsdelivr.net/npm/fluidvids@1.0.0/dist/fluidvids.min.js"></script> <!-- Replace 1.0.0 with the latest version number -->Again, ensure this script is included in your HTML <head> or before the closing </body> tag. The CDN link might change; consult the project’s documentation for the most up-to-date link.
After Installation:
No further configuration is generally needed. fluidvids.js will automatically find and process any standard video embed code within your HTML, making your videos responsive. Ensure your video embed code is correctly structured and placed within a container element with defined dimensions (e.g., width and height attributes or CSS styling). If problems arise, inspect your HTML and ensure the video embed is correctly formatted.
fluidvids.js requires minimal setup. Once included in your HTML (as described in the Getting Started section), it automatically processes any standard video embed code found within the page. There’s no need to explicitly call any functions or add data attributes to your video elements.
For example, a standard YouTube embed:
<div class="video-container">
<iframe width="560" height="315" src="https://www.youtube.com/embed/yourVideoID" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>Will be automatically made responsive. The width and height attributes within the <iframe> tag are used to determine the aspect ratio; these can be removed, but are advisable for providing fallback and initial sizing information for browsers without Javascript enabled. The key is that the <iframe> is placed inside a container (<div class="video-container"> in this example). The container’s width will determine the video’s width, while the height will adjust to maintain the aspect ratio.
The core functionality of fluidvids.js is responsive video embedding. As the browser window resizes, or the container holding the video changes dimensions, fluidvids.js dynamically adjusts the video’s dimensions to maintain its aspect ratio. This prevents distortion and ensures the video always looks its best regardless of the screen size. The library achieves this by calculating the aspect ratio from the initial dimensions given (or implied by the embed code itself) and applying proportional scaling based on the container’s width.
fluidvids.js automatically detects and respects the aspect ratio of the embedded video. This is derived primarily from the width and height attributes of the <iframe> or <video> element. If these attributes are missing or inaccurate, the library will attempt to infer the aspect ratio from the video content. In most cases, you should provide the dimensions in the embed code to ensure accuracy. There are no additional options to explicitly control the aspect ratio. Overriding the inherent aspect ratio would defeat the purpose of the library. The library focuses on maintaining the intended ratio.
You have full control over the styling of the container element holding the video. Any CSS applied to this container will affect the layout and appearance of the embedded video. For instance, you can use CSS to control the:
Example:
.video-container {
width: 100%;
max-width: 800px;
margin: 20px auto;
background-color: #f0f0f0;
border: 1px solid #ccc;
}This CSS will make the video responsive, with a maximum width of 800 pixels, centered on the page, and with a light gray background and border. Remember, the key is that fluidvids.js operates on the container, not directly on the embedded video itself.
fluidvids.js is designed to work seamlessly with various video platforms. It doesn’t require any special handling for different embed codes. Simply paste the standard embed code from YouTube, Vimeo, Wistia, or other providers into your HTML, and fluidvids.js will automatically process it. The library identifies the video type based on the src attribute of the <iframe> or <video> tag. There’s no need for platform-specific configurations or adjustments.
For example, the following Vimeo and Wistia embed codes will both be handled correctly:
Vimeo:
<div class="video-container">
<iframe src="https://player.vimeo.com/video/YOUR_VIMEO_VIDEO_ID" width="640" height="360" frameborder="0" allowfullscreen></iframe>
</div>Wistia:
<div class="video-container">
<iframe src="https://fast.wistia.net/embed/iframe/YOUR_WISTIA_HASH" allowtransparency="true" frameborder="0" scrolling="no" class="wistia_embed" name="wistia_embed" allowfullscreen mozallowfullscreen webkitallowfullscreen oallowfullscreen msallowfullscreen width="640" height="360"></iframe>
</div>Replace YOUR_VIMEO_VIDEO_ID and YOUR_WISTIA_HASH with your actual video IDs.
fluidvids.js handles multiple videos on a single page automatically. There’s no need for special configuration or looping. The library iterates through the entire DOM once and processes all qualifying video embed elements it finds. Each video will be made responsive independently.
Just ensure that each video embed is correctly placed within its own container element.
Integrating fluidvids.js with popular JavaScript frameworks like React, Angular, and Vue is straightforward. The core approach involves including the library (using either direct inclusion or a CDN) within your application, and then rendering the video embed code within your component’s JSX/template. Because fluidvids.js operates directly on the DOM, it doesn’t require specific framework integrations. The timing might require some adjustment.
Example (React):
import React, { useEffect } from 'react';
function MyVideoComponent() {
useEffect(() => {
// Ensure fluidvids.js runs *after* the DOM is fully rendered
// This might not be strictly necessary in every case, but it's a best practice.
require('fluidvids'); // Or import using module bundler
}, []);
return (
<div className="video-container">
<iframe src="https://www.youtube.com/embed/yourVideoID" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>
);
}
export default MyVideoComponent;Remember to adapt the import method to your chosen module bundler (Webpack, Parcel, etc.). The key is to run the script after the DOM is fully rendered.
fluidvids.js currently doesn’t provide a mechanism for custom events or callbacks. Its operation is entirely automated and doesn’t trigger any events after the video elements are processed. Any additional events will need to be handled using the underlying video player’s APIs (YouTube IFrame Player API, Vimeo’s API, etc.).
fluidvids.js for production deployments to reduce the file size.fluidvids.js is designed to be simple and self-contained. It doesn’t expose a large or complex API. Its core functionality operates automatically after inclusion in your HTML. However, some aspects of its behavior can be influenced and controlled through the options explained below.
fluidvids.js does not offer a fluidvids() function with options that can be directly called. Its functionality is entirely handled automatically upon inclusion in the HTML page. All configuration is done via CSS styling of the video container element. There are no parameters or options that can be passed to a fluidvids() function to alter its behavior at runtime.
fluidvids.js itself does not trigger any custom events. Any event handling needs to be done through the APIs provided by the video embedding service (YouTube IFrame API, Vimeo API, etc.). For example, if you want to respond to a video play event, you need to use the onStateChange or similar event of the YouTube IFrame Player API, not an event offered by fluidvids.js.
fluidvids.js does not expose any public methods or properties. It operates entirely passively, automatically processing video elements upon page load. There are no functions that can be called to directly interact with or manipulate the library after its initial execution. Any interaction with the videos themselves is done through the methods and properties exposed by the embedding service’s own APIs.
Videos not becoming responsive: The most common issue is incorrect HTML structure. Ensure that each video embed (<iframe> or <video>) is contained within a parent element (e.g., a <div>). This container needs to have defined dimensions (either explicitly with width and height attributes or implicitly through CSS). The width attribute of the container is crucial, as the video’s width will scale proportionally from this. Check your browser’s developer console for JavaScript errors. Ensure fluidvids.js is correctly included in your HTML.
Distorted videos: This usually indicates a problem with the aspect ratio. Double-check the width and height attributes of the embedded <iframe> or <video> tag. If they are missing or incorrect, the library might infer a wrong aspect ratio. Incorrectly specifying dimensions in CSS could also lead to this issue.
Videos not appearing at all: Verify that the video embed code itself is correct and working. Test it outside the context of fluidvids.js to rule out issues with the embed code itself. Ensure that your video hosting service is functioning correctly and that the video is publicly accessible. Check for JavaScript errors in your browser’s developer console.
Conflicts with other JavaScript libraries: Conflicts are unlikely given fluidvids.js’s minimal nature. If such a conflict occurs, carefully review your JavaScript inclusion order. If the conflict is unavoidable, consider using the direct method (download and include) rather than a CDN to ensure consistent library versions.
Browser Developer Tools: Use your browser’s developer tools (usually accessed by pressing F12) to inspect the HTML and CSS of your video containers. Check for errors in the console. Examine the computed styles to see the actual dimensions being applied.
Simplify your HTML: Create a minimal test case with just one video embed and its container to isolate the problem. This will help determine if the issue stems from your HTML structure, CSS styling, or a conflict with other code.
Inspect Network Requests: Use your browser’s developer tools to ensure fluidvids.js is correctly loaded and processed without errors. Inspect the network tab to check for loading failures.
Check your JavaScript inclusion order: Ensure fluidvids.js is included after the elements it is supposed to modify are present in the DOM.
fluidvids.js is designed to work across modern browsers. While extensive testing across all browsers and versions isn’t feasible, it should function correctly on any browser that supports modern JavaScript and CSS. Very old or outdated browsers may encounter compatibility issues. However, this is unlikely to be an issue for the majority of users in modern web environments. If you encounter problems with an older browser, try updating it. If this is impossible, you might need alternative solutions for that specific browser.
Contributions to fluidvids.js are welcome! If you find bugs, have suggestions for improvements, or want to add new features, please follow these guidelines:
Fork the Repository: Fork the official fluidvids.js repository on GitHub.
Create a Branch: Create a new branch for your contribution. Use descriptive branch names (e.g., fix/bug-responsive-on-IE11, feature/add-custom-events).
Make Your Changes: Make your code changes, ensuring they adhere to the existing coding style and conventions. Write clear and concise commit messages.
Test Thoroughly: Test your changes thoroughly to ensure they don’t introduce new bugs or regressions.
Create a Pull Request: Submit a pull request to the main repository, clearly describing your changes and their purpose.
If you encounter any bugs or have feature requests, please report them through the GitHub issue tracker: https://github.com/toddmotto/fluidvids
When reporting an issue, please provide the following information:
When submitting a pull request, follow these guidelines:
Before submitting a pull request, ensure that your code passes all automated tests (if applicable). The maintainers will review your pull request and provide feedback. Be prepared to address any comments or suggestions made during the review process.