-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add installation/usage description in README.md
- Loading branch information
Showing
1 changed file
with
151 additions
and
30 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,52 +1,173 @@ | ||
# vueginate | ||
<div align="center"> | ||
|
||
This template should help get you started developing with Vue 3 in Vite. | ||
[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/lombervid/vueginate?display_name=tag&sort=semver)](https://github.com/lombervid/vueginate) | ||
[![npm](https://img.shields.io/npm/v/vueginate)](https://www.npmjs.com/package/vueginate) | ||
[![tests](https://github.com/lombervid/vueginate/actions/workflows/tests.yml/badge.svg)](https://github.com/lombervid/vueginate/actions/workflows/tests.yml) | ||
[![GitHub](https://img.shields.io/github/license/lombervid/vueginate)](https://github.com/lombervid/vueginate/blob/main/LICENSE) | ||
|
||
## Recommended IDE Setup | ||
</div> | ||
|
||
[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin). | ||
# Vueginate | ||
|
||
## Type Support for `.vue` Imports in TS | ||
> Pagination component for Vue 3 | ||
TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) to make the TypeScript language service aware of `.vue` types. | ||
**_Vueginate_** is a simple pagination component for Vue 3 applications. It includes out-of-the-box component variants for some of the most popular CSS Frameworks, such as [_Tailwind CSS_](https://tailwindcss.com/), [_Bootstrap_](https://getbootstrap.com/) (4 and 5) and [_Bulma_](https://bulma.io/). | ||
|
||
If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a [Take Over Mode](https://github.com/johnsoncodehk/volar/discussions/471#discussioncomment-1361669) that is more performant. You can enable it by the following steps: | ||
## Installation | ||
|
||
1. Disable the built-in TypeScript Extension | ||
1) Run `Extensions: Show Built-in Extensions` from VSCode's command palette | ||
2) Find `TypeScript and JavaScript Language Features`, right click and select `Disable (Workspace)` | ||
2. Reload the VSCode window by running `Developer: Reload Window` from the command palette. | ||
```sh | ||
# or `yarn add vueginate` | `npm install vueginate` | ||
pnpm add vueginate | ||
``` | ||
|
||
## Customize configuration | ||
## Usage | ||
|
||
See [Vite Configuration Reference](https://vitejs.dev/config/). | ||
### Import the component | ||
|
||
## Project Setup | ||
Import the component and use it in your template. | ||
|
||
```sh | ||
npm install | ||
``` | ||
```html | ||
<script setup> | ||
import { reactive } from 'vue' | ||
import { Vueginate } from 'vueginate' | ||
### Compile and Hot-Reload for Development | ||
const data = reactive({ | ||
totalItems: 86, | ||
currentPage: 9, | ||
itemsPerPage: 5, | ||
}) | ||
</script> | ||
|
||
```sh | ||
npm run dev | ||
<template> | ||
<Vueginate | ||
:total-items="data.totalItems" | ||
:current-page="data.currentPage" | ||
:items-per-page="data.itemsPerPage" | ||
/> | ||
</template> | ||
``` | ||
|
||
### Type-Check, Compile and Minify for Production | ||
|
||
```sh | ||
npm run build | ||
The above example will generate a code similar to the following: | ||
|
||
```html | ||
<nav aria-label="Page navigation"> | ||
<ul class="vueginate-container"> | ||
<li> | ||
<a class="vg-item vg-arrow" href="#"> | ||
<span class="sr-only">Prev Page</span> | ||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor"> | ||
<path | ||
fill-rule="evenodd" | ||
d="M12.707 5.293a1 1 0 010 1.414L9.414 10l3.293 3.293a1 1 0 01-1.414 1.414l-4-4a1 1 0 010-1.414l4-4a1 1 0 011.414 0z" | ||
clip-rule="evenodd" | ||
/> | ||
</svg> | ||
</a> | ||
</li> | ||
<li><a class="vg-item vg-page" href="#">1</a></li> | ||
<li><span class="vg-item vg-disabled">…</span></li> | ||
<li><a class="vg-item vg-page" href="#">7</a></li> | ||
<li><a class="vg-item vg-page" href="#">8</a></li> | ||
<li><span class="vg-item vg-active" aria-current="page">9</span></li> | ||
<li><a class="vg-item vg-page" href="#">10</a></li> | ||
<li><a class="vg-item vg-page" href="#">11</a></li> | ||
<li><span class="vg-item vg-disabled">…</span></li> | ||
<li><a class="vg-item vg-page" href="#">18</a></li> | ||
<li> | ||
<a class="vg-item vg-arrow" href="#"> | ||
<span class="sr-only">Next Page</span> | ||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor"> | ||
<path | ||
fill-rule="evenodd" | ||
d="M7.293 14.707a1 1 0 010-1.414L10.586 10 7.293 6.707a1 1 0 011.414-1.414l4 4a1 1 0 010 1.414l-4 4a1 1 0 01-1.414 0z" | ||
clip-rule="evenodd" | ||
/> | ||
</svg> | ||
</a> | ||
</li> | ||
</ul> | ||
</nav> | ||
``` | ||
|
||
### Run Unit Tests with [Vitest](https://vitest.dev/) | ||
## Styling your component | ||
|
||
```sh | ||
npm run test:unit | ||
### Using default styles | ||
|
||
**_Vueginate_** includes a default styles you can import inside your script: | ||
|
||
```html | ||
<script setup> | ||
import 'vueginate/css/vueginate.css' | ||
</script> | ||
``` | ||
|
||
### Lint with [ESLint](https://eslint.org/) | ||
or from your style: | ||
|
||
```sh | ||
npm run lint | ||
```html | ||
<style> | ||
/* or `@import 'vueginate/css/vueginate.css';` */ | ||
@import 'vueginate'; | ||
</style> | ||
``` | ||
|
||
### Custom styles | ||
|
||
Or your can style your component base in the classes it has: | ||
|
||
- `vueginate-container`: pagination container `ul` | ||
- `vg-item`: every item in the list | ||
- `vg-page`: any item that is not `...`, previous/next buttons, or the current page | ||
- `vg-active`: current page | ||
- `vg-arrow`: previous/next button | ||
- `vg-disabled`: used for `...` items and for previous button (when `currentPage === 1`) and next button (when `currentPage === totalPages`) | ||
|
||
All classes are applied to the `a` (or `span` if disabled or active) element inside the `li` | ||
|
||
## Using with CSS Frameworks | ||
|
||
**_Vueginate_** includes component variants for _Tailwind_, _Bootstrap_ and _Bulma_. You can use them importing their respective component: | ||
|
||
```html | ||
<script setup> | ||
import { reactive } from 'vue' | ||
import { VueginateTailwind } from 'vueginate' | ||
import { VueginateBootstrap } from 'vueginate' | ||
import { VueginateBulma } from 'vueginate' | ||
const data = reactive({ | ||
totalItems: 86, | ||
currentPage: 9, | ||
itemsPerPage: 5, | ||
}) | ||
</script> | ||
|
||
<template> | ||
<VueginateTailwind | ||
:total-items="data.totalItems" | ||
:current-page="data.currentPage" | ||
:items-per-page="data.itemsPerPage" | ||
/> | ||
|
||
<VueginateBootstrap | ||
:total-items="data.totalItems" | ||
:current-page="data.currentPage" | ||
:items-per-page="data.itemsPerPage" | ||
/> | ||
|
||
<VueginateBulma | ||
:total-items="data.totalItems" | ||
:current-page="data.currentPage" | ||
:items-per-page="data.itemsPerPage" | ||
/> | ||
</template> | ||
``` | ||
|
||
## Roadmap | ||
|
||
- [ ] Documentation | ||
- [ ] Support to be able to change the default `ul` container to `div` | ||
- [ ] Support to have a fixed size for the component | ||
|
||
## License | ||
|
||
[MIT](https://github.com/lombervid/vueginate/blob/main/LICENSE) |