Skip to content

Commit 686f027

Browse files
committed
Readme rework
1 parent a70471d commit 686f027

File tree

1 file changed

+38
-31
lines changed

1 file changed

+38
-31
lines changed

README.md

Lines changed: 38 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -108,17 +108,52 @@ Vue.component('virtual-scroller', VirtualScroller)
108108
The virtual scroller has three main props:
109109

110110
- `items` is the list of items you want to display in the scroller. There can be several types of item.
111-
- `renderers` is a map of component definitions objects or names for each item type. If you don't define `renderers`, the scroller will use *scoped slots* ([see below](#scoped-slots)).
112111
- `itemHeight` is the display height of the items in pixels used to calculate the scroll height and position.
112+
- `renderers` is a map of component definitions objects or names for each item type ([more details](#renderers)). If you don't define `renderers`, the scroller will use *scoped slots* ([see below](#scoped-slots)).
113113

114-
The `renderers` map is an object containing a component definition for each possible value of the item type. **The component definition must have an `item` prop, that will get the item object to render in the scroller.**
114+
You need to set the size of the virtual-scroller element and the items elements (for example, with CSS). All items should have the same height to prevent display glitches.
115115

116-
Also, you need to set the size of the virtual-scroller element and the items elements (for example, with CSS). All items should have the same height to prevent display glitches.
116+
> The browsers have a height limitation on DOM elements, it means that currently the virtual scroller can't display more than ~500k items depending on the browser.
117+
118+
## Renderers
119+
120+
The optional `renderers` prop is an object containing a component definition for each possible value of the item type. If you don't set this prop, [scoped slots](#scoped-slots) will be used instead. **The component definition must have an `item` prop, that will get the item object to render in the scroller.**
117121

118122
There are additional props you can use:
119123

120124
- `typeField` to customize which field is used on the items to get their type and use the corresponding definition in the `renderers` map. The default is `'type'`.
121125
- `keyField` to customize which field is used on the items to set their `key` special attribute (see [the documation](https://vuejs.org/v2/api/#key)). The default is `'id'`.
126+
127+
## Scoped slots
128+
129+
Alternatively, you can use [scoped slots](https://vuejs.org/v2/guide/components.html#Scoped-Slots) instead of `renderers`. This is active when you don't define the `renderers` prop on the virtual scroller.
130+
131+
The scope will contain the row's item in the `item` attribute, so you can write `scope="props"` and then use `props.item`.
132+
133+
Here is an example:
134+
135+
```html
136+
<virtual-scroller class="scroller" :items="items" item-height="42" content-tag="table">
137+
<template scope="props">
138+
<tr v-if="props.item.type === 'letter'" class="letter">
139+
<td>
140+
{{props.item.value}} Scoped
141+
</td>
142+
</tr>
143+
144+
<tr v-if="props.item.type === 'person'" class="person">
145+
<td>
146+
{{props.item.value.name}}
147+
</td>
148+
</tr>
149+
</template>
150+
</virtual-scroller>
151+
```
152+
153+
## Customizing the tags
154+
155+
These are optional props you can use to change the DOM tags used in the virtual scroller:
156+
122157
- `mainTag` to change the DOM tag of the component root element. The default is `'div'`.
123158
- `containerTag` to change the DOM tag of the element simulating the height. The default is `'div'`.
124159
- `contentTag` to change the DOM tag of the element containing the items. The default is `'div'`. For example, you can change this to `'table'`.
@@ -147,34 +182,6 @@ If you set `contentTag` to `'table'`, the actual result in the DOM will look lik
147182
</div>
148183
```
149184

150-
> The browsers have a height limitation on DOM elements, it means that currently the virtual scroller can't display more than ~500k items depending on the browser.
151-
152-
## Scoped slots
153-
154-
Alternatively, you can use [scoped slots](https://vuejs.org/v2/guide/components.html#Scoped-Slots) instead of `renderers`. This is active when you don't define the `renderers` prop on the virtual scroller.
155-
156-
The scope will contain the row's item in the `item` attribute, so you can write `scope="props"` and then use `props.item`.
157-
158-
Here is an example:
159-
160-
```html
161-
<virtual-scroller class="scroller" :items="items" item-height="42" content-tag="table">
162-
<template scope="props">
163-
<tr v-if="props.item.type === 'letter'" class="letter">
164-
<td>
165-
{{props.item.value}} Scoped
166-
</td>
167-
</tr>
168-
169-
<tr v-if="props.item.type === 'person'" class="person">
170-
<td>
171-
{{props.item.value.name}}
172-
</td>
173-
</tr>
174-
</template>
175-
</virtual-scroller>
176-
```
177-
178185
# Example
179186

180187
```html

0 commit comments

Comments
 (0)