New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[lit-virtualizer] Fixes #4505 - Adds documentation for lit-virtualizer/grid #4543
base: main
Are you sure you want to change the base?
Changes from 1 commit
394c991
b2e053e
6301502
93478e2
152a65a
9a5d478
1d3ebbd
e44d2ca
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -154,7 +154,129 @@ html` | |
|
||
### Using the `grid` layout | ||
|
||
TODO | ||
The grid layout lays out uniformly sized items in a regular grid. You specify an `itemSize`, which is either strictly observed or (if you use the flex option) matched as closely as possible while taking up all space along the layout's inline axis. [You can view an example of the grid layout here](https://lit.dev/playground/#gist=a5960ffd0cb67c61083b4df0f9372eeb). | ||
|
||
_Note: When using the grid layout, Virtualizer explicitly sets the dimensions of its child elements. This differs from the behavior of the default flow layout._ | ||
|
||
```js | ||
render() { | ||
return html` | ||
<lit-virtualizer | ||
.layout=${grid({ | ||
itemSize: {width: '100px', height: '100px'} | ||
})} | ||
.items=${this.photos} | ||
.renderItem=${photos => html`<img src=${photo.url}>`} | ||
></lit-virtualizer> | ||
`; | ||
} | ||
``` | ||
|
||
#### Options | ||
|
||
The following options for available for the `grid` layout. | ||
|
||
#### gap | ||
|
||
The `gap` property determines spacing between items and can be either a single pixel value such as `8px` (the default), or by applying both a vertical and horizontal pair such as `8px 0`. | ||
|
||
Additionally `auto` can be used to split available space evenly between items, however this may only make sense for inline axis. | ||
|
||
```js | ||
render() { | ||
return html` | ||
<lit-virtualizer | ||
.layout=${grid({ | ||
itemSize: {width: '100px', height: '100px'}, | ||
gap: '0 16px' | ||
})} | ||
.items=${this.photos} | ||
.renderItem=${photos => html`<img src=${photo.url}>`} | ||
></lit-virtualizer> | ||
`; | ||
} | ||
``` | ||
|
||
#### padding | ||
|
||
The `padding` property determines the spaces around the edges and can either be a single value pair such as `8px 16px`, or four values to specify top, right, bottom, and left independently, for example `8px 12px 16px 24px`. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "around the edges" around the edges of items? If so I'd say that, and if possible clarify the difference between padding and gap. Maybe "around each item" would be enough to imply the difference and most people should be familiar with the concepts from CSS? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I like that change 👍🏻 |
||
|
||
|
||
```js | ||
render() { | ||
return html` | ||
<lit-virtualizer | ||
.layout=${grid({ | ||
itemSize: {width: '100px', height: '100px'}, | ||
padding: '8px 12px' | ||
})} | ||
.items=${this.photos} | ||
.renderItem=${photos => html`<img src=${photo.url}>`} | ||
></lit-virtualizer> | ||
`; | ||
} | ||
``` | ||
|
||
You can also set `padding` to `match-gap` to make the outer spacing match the inner spacing. | ||
|
||
```js | ||
render() { | ||
return html` | ||
<lit-virtualizer | ||
.layout=${grid({ | ||
itemSize: {width: '100px', height: '100px'}, | ||
gap: '8px', | ||
padding: 'match-gap' | ||
})} | ||
.items=${this.photos} | ||
.renderItem=${photos => html`<img src=${photo.url}>`} | ||
></lit-virtualizer> | ||
`; | ||
} | ||
``` | ||
|
||
#### justify | ||
|
||
The `justify` property defines how space is distributed between and around each item. Setting `justify` overrides any `gap` values provided for the inline axis. | ||
|
||
The available options for `justify` are `start` | `center` | `end` | `space-evenly` | `space-around` | `space-between`. | ||
|
||
```js | ||
render() { | ||
return html` | ||
<lit-virtualizer | ||
.layout=${grid({ | ||
itemSize: {width: '100px', height: '100px'}, | ||
justify: 'space-around' | ||
})} | ||
.items=${this.photos} | ||
.renderItem=${photos => html`<img src=${photo.url}>`} | ||
></lit-virtualizer> | ||
`; | ||
} | ||
``` | ||
|
||
#### flex | ||
|
||
When `flex` is specified, item size will be auto-adjusted so that items take up all available space along the inline axis while maintaining the provided `gap` value. `flex: true` is equivalent to `flex: {preserve: 'area'}`. | ||
|
||
The available options for `flex` are `true`| `false`| `{preserve: 'aspect-ratio' | 'area' | 'width' | 'height'}` | ||
|
||
```js | ||
render() { | ||
return html` | ||
<lit-virtualizer | ||
.layout=${grid({ | ||
itemSize: {width: '100px', height: '100px'}, | ||
flex: true | ||
})} | ||
.items=${this.photos} | ||
.renderItem=${photos => html`<img src=${photo.url}>`} | ||
></lit-virtualizer> | ||
`; | ||
} | ||
``` | ||
|
||
|
||
### Scrolling | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Regarding "however this may only make sense for inline axis" does
auto
even do anything for the block axis? If not, I'd say "however this only works for the inline axis". If it does do something for the block axis it'd be good to say what that is.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Tried to check on this, but I am running into some issues. I based this particular example on the playground, but it seems like the
auto
property may be bugged, or I'm just misunderstanding how it works.The following produces this error:
Error: grid layout: column-gap cannot be set to 'auto' when direction is set to vertical
, but from what I can telldirection
doesn't actually work for a grid layout, as changing it at all causes the virtualizer to disappear.Perhaps I should omit documenting the auto property for now? Regardless I've added some additional context surrounding the
justify
requirement which was missing before.