Skip to content

Commit 1cf2c27

Browse files
liabruliabru
committed
improved readme
1 parent f4b4b98 commit 1cf2c27

File tree

1 file changed

+55
-37
lines changed

1 file changed

+55
-37
lines changed

‎README.md

+55-37
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# jquery.matchHeight.js #
22

3-
> *matchHeight* makes the height of all selected elements exactly equal.<br>
3+
> *matchHeight* makes the height of all selected elements exactly equal.
44
It handles many edge cases that cause similar plugins to fail.
55

66
[brm.io/jquery-match-height](http://brm.io/jquery-match-height/)
@@ -28,18 +28,20 @@ See the [jquery.matchHeight.js demo](http://brm.io/jquery-match-height-demo).
2828
- maintain scroll position
2929
- data attributes API
3030
- callback events
31-
- tested in IE8+, Chrome, Firefox, Chrome Android
31+
- unit tests
32+
- module loader support
33+
- tested in IE8+, Chrome, Firefox, Safari, Android, iOS
3234

3335
### Status
3436

35-
Current version is `v0.6.0`. <br>
36-
Use the master build for the latest features. <br>
37+
Current version is `0.6.0`.
38+
Use the master build for the latest features.
3739
Please report any [issues](https://github.com/liabru/jquery-match-height/issues) you find.
3840

3941
### Install
4042

4143
[jQuery](http://jquery.com/download/) is required, so include it first.
42-
<br>Download [jquery.matchHeight.js](https://github.com/liabru/jquery-match-height/blob/master/jquery.matchHeight.js) and include the script in your HTML file:
44+
Download [jquery.matchHeight.js](https://github.com/liabru/jquery-match-height/blob/master/jquery.matchHeight.js) and include the script in your HTML file:
4345

4446
<script src="jquery.matchHeight.js" type="text/javascript"></script>
4547

@@ -50,26 +52,31 @@ You can also install using the package managers [Bower](http://bower.io/search/?
5052

5153
### Usage
5254

53-
$(elements).matchHeight(options);
55+
$(function() {
56+
$('.item').matchHeight(options);
57+
});
5458

55-
Where options is an optional parameter. <br>
59+
Where `options` is an optional parameter.
5660
See below for a description of the available options and defaults.
5761

58-
Call this on the [DOM ready](http://api.jquery.com/ready/) event (the plugin will automatically update on window load). <br>
59-
See below for examples or the included [test.html](https://github.com/liabru/jquery-match-height/blob/master/test.html).
62+
The above example will set all selected elements with the class `item` to the height of the tallest.
63+
If the items are on multiple rows, the items of each row will be set to the tallest of that row (see `byRow` option).
64+
65+
Call this on the [DOM ready](http://api.jquery.com/ready/) event (the plugin will automatically update on window load).
66+
See the included [test.html](https://github.com/liabru/jquery-match-height/blob/master/test/page/test.html) for many working examples.
6067

6168
Also see the [Data API](#data-api) below for a simple, alternative inline usage.
6269

6370
### Options
6471

65-
The default options are:
72+
The default `options` are:
6673

67-
$(elements).matchHeight({
74+
{
6875
byRow: true,
6976
property: 'height',
7077
target: null,
7178
remove: false
72-
});
79+
}
7380

7481
Where:
7582

@@ -78,51 +85,60 @@ Where:
7885
- `target` is an optional element to use instead of the element with maximum height
7986
- `remove` is `true` or `false` to remove previous bindings instead of applying new ones
8087

81-
### Examples
82-
83-
$(function() {
84-
$('.item').matchHeight();
85-
});
86-
87-
The above will set all elements with the class `item` to the height of the tallest.<br>
88-
If the items are on multiple rows, the items of each row will be set to the tallest of that row (see `byRow`).
89-
90-
$(function() {
91-
$('.item').matchHeight({
92-
target: $('.sidebar')
93-
});
94-
});
88+
### Data API
9589

96-
The above will set all elements with the class `item` to the height of the first item with class `sidebar`.
90+
Use the data attribute `data-mh="group-name"` where `group-name` is an arbitrary string to identify which elements should be considered as a group.
9791

9892
<div data-mh="my-group">My text</div>
9993
<div data-mh="my-group">Some other text</div>
10094
<div data-mh="my-other-group">Even more text</div>
10195
<div data-mh="my-other-group">The last bit of text</div>
10296

103-
The above will set both elements in `my-group` to the same height as each other.
104-
It will set both elements in `my-other-group` to be the same height as each other.
105-
106-
See the included [test.html](https://github.com/liabru/jquery-match-height/blob/master/test.html) for a working example.
107-
108-
### Data API
109-
110-
Use the data attribute `data-mh="group-name"` where `group-name` is an arbitrary string to identify which elements should be considered as a group.
111-
11297
All elements with the same group name will be set to the same height when the page is loaded, regardless of their position in the DOM, without any extra code required.
11398

11499
Note that `byRow` will be enabled when using the data API, if you don't want this (or require other options) then use the alternative method above.
115100

116101
### Advanced Usage
117102

118-
There are a few internal properties and functions you should know about:
103+
There are some additional functions and properties you should know about:
119104

120105
#### Manually trigger an update
121106

122107
$.fn.matchHeight._update()
123108

124109
If you need to manually trigger an update of all currently set groups, for example if you've modified some content.
125110

111+
#### Row detection
112+
113+
You can toggle row detection by setting the `byRow` option, which defaults to `true`.
114+
It's also possible to use the row detection function at any time:
115+
116+
$.fn.matchHeight._rows($('.item'));
117+
118+
Which will return an array of element selections for each row, see [this thread](https://github.com/liabru/jquery-match-height/issues/90) for more information and an example.
119+
120+
#### Remove bindings
121+
122+
$('.item').matchHeight({ remove: true });
123+
124+
This will remove all bindings for the selected elements, from all groups.
125+
126+
#### Custom target element
127+
128+
$(function() {
129+
$('.item').matchHeight({
130+
target: $('.sidebar')
131+
});
132+
});
133+
134+
Will set all selected elements to the height of the first item with class `sidebar`.
135+
136+
#### Custom property
137+
138+
$('.item').matchHeight({ property: 'min-height' });
139+
140+
This will set the `min-height` property instead of the `height` property.
141+
126142
#### Callback events
127143

128144
Since matchHeight automatically handles updating the layout after certain window events, you can supply functions as global callbacks if you need to be notified:
@@ -198,6 +214,8 @@ If this is a problem, you should call `_update` once your font has loaded by usi
198214

199215
If you change the content inside an element that has had `matchHeight` applied, then you must manually call `$.fn.matchHeight._update()` afterwards. This will update of all currently set equal heights groups.
200216

217+
Also note that previous matchHeight bindings do not apply to new elements, even if they match the selector used. In this case you must remove the old bindings and add new ones, see [this comment](https://github.com/liabru/jquery-match-height/issues/60#issuecomment-155913995).
218+
201219
### Changelog
202220

203221
To see what's new or changed in the latest version, see the [changelog](https://github.com/liabru/jquery-match-height/blob/master/CHANGELOG.md)

0 commit comments

Comments
 (0)