JavaScript plugin to make elements the same height across different containers.
In fact, this is a crutch, but it's necessary until we get CSS Subgrid ready.
If you can use CSS Subgrid - use it.
This plugin tries to do literally the same, but, of course, is less performant than browsers can do.
Plugin is written in pure JavaScript, so it can be called "framework agnostic".
There is already a version for Vue 2 and 3 done via directives.
yarn add @morev/equal-heights
npm install @morev/equal-heights
pnpm add @morev/equal-heights
import { EqualHeights } from '@morev/equal-heights';
const equalHeights = new EqualHeights({
/* custom options for all groups of elements (optional) */
});
equalHeights.add([
{ selector: '.some-selector', options: { /* custom options for this group of elements (optional) */ } },
{ selector: '.another-selector' },
]);
byRows
Whether only the elements in the same row should have equal height, instead of all the elements in stack.
// Default: true
export type OptionByRows = boolean;
isEnabled
A function to test whether the elements should have the equal height. Accepts the window
object as the argument.
Returns a value that coerces to true
to set equal height, or to false
otherwise.
// Default: () => true
export type OptionIsEnabled = (window: Window) => boolean;
isDisabled
A function to test whether the elements should not have the equal height. Accepts the window
object as the argument.
Returns a value that coerces to true
to unset equal height, or to false
otherwise.
// Default: () => false
export type OptionIsDisabled = (window: Window) => boolean;
resizeObserver
Whether to observe resizing of the elements using the ResizeObserver
.
// Default: true
export type OptionResizeObserver = boolean;
mutationObserver
Whether to observe adding/removing of the elements using the MutationObserver
.
// Default: true
export type OptionMutationObserver = boolean;
parent
Common parent element of a given elements.
// Default: document.body
export type OptionMutationObserver = HTMLElement;
add
Adds a new group(s) of elements and (optionally) its specific options.
Parameters:
Name | Type | Description |
---|---|---|
input* | string|string[]|object|object[] |
Elements selector, an object structured of { selector: string, options?: object } , or an array of such objects. |
Returns:
EqualHeights
- The class instance.
Example:
import { EqualHeights } from '@morev/equal-heights';
const equalHeights = new EqualHeights();
equalHeights.add('.selector-one');
equalHeights.add({ selector: '.selector-two', options: { /* custom options (optional) */ } });
equalHeights.add([
{ selector: '.selector-three', options: { /* custom options (optional) */ } },
{ selector: '.selector-four' },
]);
remove
Removes the elements from the stack.
Parameters:
Name | Type | Description |
---|---|---|
selector* | string |
Selector of the elements being de-registered. |
parent | HTMLElement|undefined |
Common parent element. |
Returns:
EqualHeights
- The class instance.
Example:
import { EqualHeights } from '@morev/equal-heights';
const equalHeights = new EqualHeights();
equalHeights.add([
{ selector: '.some-selector', options: { parent: document.querySelector('.parent-selector') } },
{ selector: '.another-selector' },
]);
// ...
equalHeights.remove('.some-selector', document.querySelector('.parent-selector'));
// only the `.another-selector` elements are being processed now
update
Returns:
EqualHeights
- The class instance.
Example:
import { EqualHeights } from '@morev/equal-heights';
const equalHeights = new EqualHeights();
equalHeights.add([
{ selector: '.some-selector' },
{ selector: '.another-selector' },
]);
// ...
equalHeights.update(); // manually update all the registered elements sizes
reset
Restores the initial state of all the registered elements and removes it from the stack.
Returns:
EqualHeights
- The class instance.
Example:
import { EqualHeights } from '@morev/equal-heights';
const equalHeights = new EqualHeights();
equalHeights.add([
{ selector: '.some-selector' },
{ selector: '.another-selector' },
]);
// ...
equalHeights.reset(); // there are no elements being processed now
The Vue module (2 and 3 both) distributes in the same package and avaliable via a named export called /vue
.
In fact, there are three exports: /vue
, /vue2
and /vue3
, and main /vue
export is dynamical - it mapped to version of Vue used in your project.
Underhood, it utilized the postinstall npm hook.
After installing the package, the script will start to check the installed Vue version and redirect the exports to based on the local Vue version.
If no Vue installation is found, the script will install the version for Vue 3 as default.
It feels pretty robust, but if you're worried about, prefer an explicit named import according to the version you're using.
There are also CLI to switch mapping of main export:
yarn equal-heights-vue-version <version>
, where<version>
is "2" of "3"
😥 I got an error "This dependency was not found"
For environments that can't resolve exports
field (such as Nuxt 2)
just replace import with direct path to file:
import { plugin as EqualHeights } from '@morev/equal-heights/dist/vue.cjs';
import Vue from 'vue';
import { plugin as EqualHeights } from '@morev/equal-heights/vue';
Vue.use(EqualHeights);
import { createApp } from 'vue';
import { plugin as EqualHeights } from '@morev/equal-heights/vue';
const app = createApp(App);
app.use(EqualHeights);
<template>
<ul class="list" v-equal-heights="'.item-title'">
// ...
</ul>
</template>
<script>
import { directive as equalHeights } from '@morev/equal-heights/vue';
export default {
name: 'some-component',
directives: { equalHeights },
// ...
}
</script>
<template>
<ul v-equal-heights="'.item-tags'">
<li v-for="item in items" :key="item.id">
<div class="item-tags">...</div>
<img class="item-image" src="..." alt="Product image" />
<div class="item-title">...</div>
</li>
</ul>
</template>
<template>
<ul v-equal-heights="['.item-tags', '.item-title']">
<li v-for="item in items" :key="item.id">
<div class="item-tags">...</div>
<img class="item-image" src="..." alt="Product image" />
<div class="item-title">...</div>
</li>
</ul>
</template>
<template>
<ul
v-equal-heights="{
selector: '.item-tags', // May also be an array of strings
options: {
isEnabled: (window) => window.innerWidth >= 768,
}
}"
>
<li v-for="item in items" :key="item.id">
<div class="item-tags">...</div>
<img class="item-image" src="..." alt="Product image" />
<div class="item-title">...</div>
</li>
</ul>
</template>
<template>
<ul
v-equal-heights="[
{
selector: '.item-tags', // May also be an array of strings
options: {
isEnabled: (window) => window.innerWidth >= 768,
}
},
{
selector: '.item-title', // May also be an array of strings
options: {
isEnabled: (window) => isAligned && window.innerWidth >= 360,
}
}
]"
>
<li v-for="item in items" :key="item.id">
<div class="item-tags">...</div>
<img class="item-image" src="..." alt="Product image" />
<div class="item-title">...</div>
</li>
</ul>
</template>