Class SameHeight

Configures the given element as a SameHeight widget.

The SameHeight widget sets up the given element as a flexbox and sets the flex basis of its components so that their heights are as close as possible to each other. It tracks their size (see SizeWatcher) and continually updates the basis as needed.

When calculating the best flex basis that would result in equal heights, SameHeight determines whether a flex child is mostly text or mostly images since the height of these scales in opposite manner with their width. Therefore, the components of the widget should contain either mostly text or mostly images.

The widget should have more than one item and the items must be immediate children of the container element.

SameHeight tries to automatically determine if an item is mostly text or mostly images based on the total display text content, but you can override this in two ways:

  1. By passing a map of elements as items instead of an array, and setting the value for each to either "text" or "image"
  2. By setting the data-lisn-same-height-item attribute to "text" or "image" on the children. NOTE however that when auto-discovering the items (i.e. when you have not explicitly passed a list/map of items), if you set the data-lisn-same-height-item attribute on any child you must also add this attribute to all other children that are to be used by the widget. Other children (that don't have this attribute) will be ignored and assumed to be either zero-size or position absolute/fixed.

IMPORTANT: You should not instantiate more than one SameHeight widget on a given element. Use SameHeight.get to get an existing instance if any. If there is already a widget instance, it will be destroyed!

IMPORTANT: The element you pass will be set to display: flex and its children will get box-sizing: border-box and continually updated flex-basis style. You can add additional CSS to the element or its children if you wish. For example you may wish to set flex-wrap: wrap on the element and a min-width on the children.

To use with auto-widgets (HTML API) (see settings.autoWidgets), the following CSS classes or data attributes are recognized:

  • lisn-same-height class or data-lisn-same-height attribute set on the container element that constitutes the widget.

When using auto-widgets, the elements that will be used as items are discovered in the following way:

  1. The immediate children of the top-level element that constitutes the widget that have the lisn-same-height-item class or data-lisn-same-height-item attribute are taken.
  2. If none of the root's children have this class or attribute, then all of the immediate children of the widget element except any script or style elements are taken as the items.

See below examples for what values you can use set for the data attribute in order to modify the configuration of the automatically created widget.

Example

This defines a simple SameHeight widget with one text and one image child.

<div class="lisn-same-height">
  <div>
    <p>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
      eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
      minim veniam, quis nostrud exercitation ullamco laboris nisi ut
      aliquip ex ea commodo consequat. Duis aute irure dolor in
      reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
      pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
      culpa qui officia deserunt mollit anim id est laborum.
    </p>
  </div>

  <div>
    <img
      src="https://www.wikipedia.org/portal/wikipedia.org/assets/img/Wikipedia-logo-v2@1.5x.png"
    />
  </div>
</div>

Example

This defines a SameHeight widget with the flexbox children specified explicitly (and one ignored), as well as having all custom settings.

<div data-lisn-same-height="diff-tolerance=20
                            | resize-threshold=10
                            | debounce-window=50
                            | min-gap=50
                            | max-free-r=0.2
                            | max-width-r=3.2">
  <div>Example ignored child</div>

  <div data-lisn-same-height-item><!-- Will be detected as text anyway -->
    <p>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
      eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
      minim veniam, quis nostrud exercitation ullamco laboris nisi ut
      aliquip ex ea commodo consequat. Duis aute irure dolor in
      reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
      pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
      culpa qui officia deserunt mollit anim id est laborum.
    </p>
  </div>

  <!-- Explicitly set to image type, though it will be detected as such -->
  <div data-lisn-same-height-item="image">
    <img
      src="https://www.wikipedia.org/portal/wikipedia.org/assets/img/Wikipedia-logo-v2@1.5x.png"
    />
  </div>

  <!-- Explicitly set to text type, because it will NOT be detected as such (text too short). -->
  <div data-lisn-same-height-item="text">
    <p>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    </p>
  </div>
</div>

Hierarchy (View Summary)

Methods

get register

Constructors

constructor

Properties

destroy disable enable getElement getItemConfigs getItems isDestroyed isDisabled onDestroy onDisable onEnable toColumn toggleEnable toRow

Methods

Staticget

Staticregister

Constructors

constructor

Properties

Readonlydestroy

destroy: () => Promise<void>

Undoes all modifications to the element and returns it to its original state.

You will need to recreate it if you want to enable its functionality again.

Readonlydisable

disable: () => Promise<void>

Disables the functionality of the widget. What this means is specific to each widget.

Readonlyenable

enable: () => Promise<void>

Re-enables the functionality of the widget. What this means is specific to each widget.

ReadonlygetElement

getElement: () => Element

Returns the element passed to the widget constructor.

ReadonlygetItemConfigs

getItemConfigs: () => Map<Element, "image" | "text">

Returns a map of the elements used as the flex children with their type.

ReadonlygetItems

getItems: () => Element[]

Returns the elements used as the flex children.

ReadonlyisDestroyed

isDestroyed: () => boolean

Returns true if the widget is destroyed.

ReadonlyisDisabled

isDisabled: () => boolean

Returns true if the widget is currently disabled.

ReadonlyonDestroy

onDestroy: (handler: WidgetHandler) => void

The given handler will be called when the widget is destroyed.

ReadonlyonDisable

onDisable: (handler: WidgetHandler) => void

The given handler will be called when the widget is disabled.

ReadonlyonEnable

onEnable: (handler: WidgetHandler) => void

The given handler will be called when the widget is enabled.

ReadonlytoColumn

toColumn: () => Promise<void>

Switches the flexbox to vertical (column) mode.

You can alternatively do this by setting the data-lisn-orientation="vertical" attribute on the element at any time.

You can do this for example as part of a trigger:

Example

<div class="lisn-same-height"
     data-lisn-on-layout="max-mobile-wide:set-attribute=data-lisn-orientation#vertical">
     <!-- ... children -->
</div>

ReadonlytoggleEnable

toggleEnable: () => Promise<void>

Re-enables the widget if disabled, otherwise disables it.

ReadonlytoRow

toRow: () => Promise<void>

Switches the flexbox back to horizontal (row) mode, which is the default.

You can alternatively do this by deleting the data-lisn-orientation attribute on the element, or setting it to "horizontal" at any time.

Settings

Member Visibility

On This Page

Methods
Constructors
Properties