fit-to-parent
v1.3.61
Published
A tool that will resize a DOM element to fit its parent container while maintaining the original aspect ratio.
Downloads
483
Readme
What is it?
fitToParent is a tool that will resize a DOM element to fit its parent container while maintaining its original aspect ratio. Kind of like background-size: contain;
for anything.
Installation
Just grab fitToParent.min.js
from this repo and include it in the head of your page. If using with jQuery or Zepto, make sure fitToParent is called after the core library.
If you're use NPM or yarn:
npm install fit-to-parent --save
Basics
If you have an iframe that needs to fit to its parent element:
var vid = document.querySelector('iframe');
// sets iframe size
fitToParent(vid);
// Most of the time we will need to update on resize as well
window.addEventListener('resize', function(){
fitToParent(vid);
});
You can either pass a DOM element to fitToParent, like the example above, or you can pass an object of options including the element like so:
fitToParent({
element: vid,
heightOffset: 200
})
When using jQuery or Zepto, fitToParent will just attach itself as a plugin:
$('iframe').fitToParent();
$(window).on('resize', function(){
$('iframe').fitToParent();
});
Aspect Ratio
When sizing the element, fitToParent will need to know the aspect ratio of the element. Unless explicitly set, fitToParent will attempt to calculate the ratio of the element automatically. This happens once the first time it's called on that particular element, and then it will use the calculated value each consecutive call.
When determining the ratio for a single element, fitToParent will run in this order:
- Ratio set manually in options (see 'Options' below)
- Ratio defined as a data attribute on the element, as the property 'aspect'
- Calculated ratio using the sizes passed to
elHeight
andelWidth
(see 'Options' below) - Calculated ratio using the
height
andwidth
attributes set directly on the element - Calculated ratio using the intended
height
andwidth
of the element as set in css - If none of these options are available, fitToParent will measure the height and width of the element directly as rendered in the DOM and calculate the ratio from that
examples:
for this markup:
<div class="stage">
<iframe src="https://vimeo...." width="640" height="360"></iframe>
</div>
Calling $('iframe').fitToParent()
will calculate the ratio based on attributes, so it will come up with 1.77 (which is 640 / 360).
Calling $('iframe').fitToParent({ elWidth: 1920, elHeight: 800 })
will calculate with the provided dimensions and come up with 2.4
Calling $('iframe').fitToParent({ ratio: 2 })
will use the provided value of 2.
Parent element
When determining the size of the parent to fit to, fitToParent looks in this order:
- Sizes passed into
parentHeight
andparentWidth
(see 'Options' below) - The size of the closest ancestor element with the class
size-parent
- If no
.size-parent
found, then it uses the size of the direct parent element
examples:
Calling $('iframe').fitToParent()
will use the above logic to figure out the intended size.
Calling $('iframe').fitToParent({ parentHeight: 200 })
will use 200px as the parent height and the width of .size-parent
as the parent width.
Example
An example of a common Vimeo embed sized and centered in the window
<div class="stage">
<iframe src="https://player.vimeo.com/video/20744468" width="640" height="360"></iframe>
</div>
.stage {
height: 100vh;
width: 100%;
display: flex;
}
iframe {
margin: auto;
}
$(document).ready(function(){
$('iframe').fitToParent();
$(window).on('resize', function(){
$('iframe').fitToParent();
});
}):
You can find full examples in the "examples" folder of this repo.
Options
Common options for basic use
fitToParent({
element: null, // (obj) Dom element to set size for (not needed with jQuery or Zepto)
heightOffset: 0, // (int) Put some space around the element
widthOffset: 0, // (int) Put some space around the element
upres: true, // (bool) allows fitToParent to size the target element above initial size
maxWidth: Infinity, // (int) max width in pixels
maxHeight: Infinity,// (int) max height in pixels
callback: function([newWidth, newHeight]){
// Fires after fitting is complete
// this === element
}
});
Less common options when manual overrides are needed:
fitToParent({
parentHeight: null, // (int) Height to fit to, defaults to parent height
parentWidth: null, // (int) Width to fit to, defaults to parent width
elHeight: null, // (int) Starting height of element, see "aspect Ratio" above for default value
elWidth: null, // (int) Starting width of element, see "aspect Ratio" above for default value
ratio: null, // (float) Intended aspect ratio of element (width/height). Uses info from DOM by default
})
It's important to note that fitToParent is not an asynchronous operation. When used purely as a function it will return its output synchronously. That being said, it's still often useful to have a callback when using fitToParent as a jQuery plugin.
Advanced usage
Using with jQuery/Zepto
If you're using fitToParent in a module system and you want it to act as a jQuery/Zepto plugin:
- Import jQuery first
- Import fitToParent with:
import 'fitToParent/dist/fitToParent.min'
This way you'll be able to use fitToParent like this:
jQuery('.selector').fitToParent({})
DOM-less use
fitToParent may be useful to you even in environments with no DOM. There's no reason an element has to be provided as an argument, you could set the numbers manually and only use the return value like this:
import fitToParent from 'fit-to-parent'
// fitting a square into a 16:9 container
const [newWidth, newHeight] = fitToParent({
ratio: 1,
parentWidth: 1920,
parentHeight: 1080
})
// do something with calculated dimensions
Development
npm install
npm run dev
Runs a webpack dev server and opens the page.
Structure
FitToParent consists of two main sections:
- the
fitToParent
function, a calculator based on aspect ratios, offsets, and other options - the
src/webpack-entry.js
functionality, which ties that calculator to jQuery, Zepto, or vanilla JS.
The fitToParent doesn't assume that a browser exists, instead just giving you access to the basic calculator functions of the plugin. webpack-entry
, on the other hand, assumes a browser environment, plugging into (in order of most to least preferred) jQuery, Zepto, or the window as a global function.
More Info
Originally by Drew Baker, based on improvements to the answer from @TrueBlueAussie developed over time.
fitToParent
http://funkhaus.us