|
| 1 | +# StackGrid for Vue 3 |
| 2 | + |
| 3 | +StackGrid is a Vue 3 component designed to make it easy and efficient to create dynamic, responsive grid layouts. It automatically arranges items based on the available container width, ensuring a visually appealing presentation on all devices. |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +## Demo |
| 8 | +See the [demo](https://vue-stack-grid.crobert.dev/) for a live example of StackGrid in action. |
| 9 | + |
| 10 | +## Features |
| 11 | + |
| 12 | +- **Responsive**: Automatically adjusts to the container's width. |
| 13 | +- **Customizable**: Offers props for minimum column width, gutter width, and gutter height. |
| 14 | +- **Slot Support**: Utilize slots to customize the content of each grid item. |
| 15 | +- **Vue 3 Composition API**: Built with Vue 3's Composition API for better performance and readability. |
| 16 | + |
| 17 | +## Installation |
| 18 | + |
| 19 | +To install StackGrid, use npm or yarn: |
| 20 | + |
| 21 | +``` |
| 22 | +npm i @crob/vue-stack-grid |
| 23 | +``` |
| 24 | + |
| 25 | +or |
| 26 | + |
| 27 | +``` |
| 28 | +yarn add @crob/vue-stack-grid |
| 29 | +``` |
| 30 | + |
| 31 | +## Usage |
| 32 | + |
| 33 | +Import StackGrid into your component and use it in your template. Provide it with the necessary props like `items`, `columnMinWidth`, `gutterWidth`, and `gutterHeight`. Use the slot `item` to customize how each item in the grid should be displayed. |
| 34 | + |
| 35 | +```vue |
| 36 | +<template> |
| 37 | + <StackGrid :items="items" :column-min-width="100" :gutter-width="10" :gutter-height="10"> |
| 38 | + <template #item="{ item }"> |
| 39 | + <div>{{ item }}</div> |
| 40 | + </template> |
| 41 | + </StackGrid> |
| 42 | +</template> |
| 43 | +
|
| 44 | +<script setup> |
| 45 | +import StackGrid from '@crob/vue-stack-grid'; |
| 46 | +const items = [...]; // your items here |
| 47 | +</script> |
| 48 | +``` |
| 49 | + |
| 50 | +## Props |
| 51 | + |
| 52 | +- **items** (required): An array of items to display in the grid. |
| 53 | +- **columnMinWidth** (required): The minimum width of each column in pixels. |
| 54 | +- **gutterWidth**: The horizontal gap between columns in pixels. Default is `0`. |
| 55 | +- **gutterHeight**: The vertical gap between rows in pixels. Default is `0`. |
| 56 | + |
| 57 | +## Events |
| 58 | + |
| 59 | +### `updated:reflow` |
| 60 | + |
| 61 | +The `updated:reflow` event is emitted after the grid layout has been recalculated. This can occur in response to various triggers, such as a window resize or manual invocation of the reflow process. This event provides a way for parent components to react to changes in the grid layout, enabling additional custom behavior or UI updates based on the new layout state. |
| 62 | + |
| 63 | +#### Listening to the Event |
| 64 | + |
| 65 | +To listen to the `updated:reflow` event, attach an event listener to the `<StackGrid>` component in your template. You can then define a method within your component to handle the event. |
| 66 | + |
| 67 | +```vue |
| 68 | +<template> |
| 69 | + <StackGrid @updated:reflow="handleReflowEvent"></StackGrid> |
| 70 | +</template> |
| 71 | +
|
| 72 | +<script setup> |
| 73 | +import { defineComponent } from 'vue'; |
| 74 | +import StackGrid from '@crob/vue-stack-grid'; |
| 75 | +
|
| 76 | +const handleReflowEvent = () => { |
| 77 | + console.log('Grid layout was updated.'); |
| 78 | + // Additional logic to handle the grid update... |
| 79 | +}; |
| 80 | +</script> |
| 81 | +``` |
| 82 | + |
| 83 | + |
| 84 | +## Methods |
| 85 | + |
| 86 | +### `reflow` |
| 87 | + |
| 88 | +Triggers a reflow of the grid layout. This can be useful if you've dynamically changed the items or their sizes and need to re-calculate the layout of the grid. |
| 89 | +To use this method, you'll need to get a reference to the StackGrid component instance in your parent component. Here's an example of how to do this with Vue 3's Composition API: |
| 90 | + |
| 91 | +```vue |
| 92 | +<template> |
| 93 | + <StackGrid ref="stackGridRef" :items="items" :columnMinWidth="100" :gutterWidth="10" :gutterHeight="10"> |
| 94 | + <template #item="{ item }"> |
| 95 | + <div>{{ item }}</div> |
| 96 | + </template> |
| 97 | + </StackGrid> |
| 98 | + <button @click="reflowGrid">Reflow Grid</button> |
| 99 | +</template> |
| 100 | +
|
| 101 | +<script setup> |
| 102 | +import { ref } from 'vue'; |
| 103 | +import StackGrid from '@crob/vue-stack-grid'; |
| 104 | +
|
| 105 | +const stackGridRef = ref(); |
| 106 | +const items = ref([...]); // Your items here |
| 107 | +
|
| 108 | +function reflowGrid() { |
| 109 | + if (stackGridRef.value) { |
| 110 | + stackGridRef.value.reflow(); |
| 111 | + } |
| 112 | +} |
| 113 | +</script> |
| 114 | +``` |
| 115 | + |
| 116 | +This section demonstrates how to access and call the `reflow` method exposed by the StackGrid component. |
| 117 | + |
| 118 | +## Contributing |
| 119 | + |
| 120 | +Contributions are welcome! If you have an idea or suggestion, please feel free to fork the repository, make your changes, and submit a pull request. |
| 121 | + |
| 122 | +## License |
| 123 | + |
| 124 | +This project is licensed under the MIT License - see the LICENSE file for details. |
0 commit comments