{"id":13820909,"url":"https://github.com/bramus/js-pagination-sequence","last_synced_at":"2025-04-07T09:19:42.699Z","repository":{"id":42645718,"uuid":"435299039","full_name":"bramus/js-pagination-sequence","owner":"bramus","description":"Generate a sequence of numbers for use in a pagination system, the clever way.","archived":false,"fork":false,"pushed_at":"2023-07-18T20:10:02.000Z","size":146,"stargazers_count":140,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-01T23:16:08.335Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bramus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-05T22:58:32.000Z","updated_at":"2024-05-28T09:52:31.809Z","dependencies_parsed_at":"2024-05-28T09:52:27.511Z","dependency_job_id":"fd11758c-3346-4c84-929c-399b60dc3e4d","html_url":"https://github.com/bramus/js-pagination-sequence","commit_stats":{"total_commits":29,"total_committers":1,"mean_commits":29.0,"dds":0.0,"last_synced_commit":"fbd917efbee3661227c4634b62ff1e1b1500a68b"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fjs-pagination-sequence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fjs-pagination-sequence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fjs-pagination-sequence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bramus%2Fjs-pagination-sequence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bramus","download_url":"https://codeload.github.com/bramus/js-pagination-sequence/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622983,"owners_count":20968575,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T08:01:11.507Z","updated_at":"2025-04-07T09:19:42.676Z","avatar_url":"https://github.com/bramus.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![JavaScript Pagination Sequence Generator](./screenshots/js-pagination-sequence.png)](https://codepen.io/bramus/pen/NWaxNKQ)\n\n# JavaScript Pagination Sequence Generator\n\nGenerate a sequence of numbers for use in a Pagination Component, the clever way.\n\n## Installation\n\n```bash\nnpm i @bramus/pagination-sequence\n```\n\n## Usage / Example\n\nThis library comes as an ES Module and exposes a function/algorithm to generate an array of pagination entries.\n\n```js\nimport { generate } from '@bramus/pagination-sequence';\n\nconst sequence = generate(67, 74);\n// ~\u003e [1, 2, '…', 65, 66, 67, 68, 69, '…', 73, 74]\n```\n\nAlternatively you can use `generateFromObj` which accepts a configuration Object as an argument:\n\n```js\nimport { generateFromObj } from '@bramus/pagination-sequence';\n\nconst sequence = generateFromObj({\n    curPage: 67,\n    numPages: 74,\n});\n// ~\u003e [1, 2, '…', 65, 66, 67, 68, 69, '…', 73, 74]\n```\n\nNote that this is a Framework Agnostic library: the generated array is not rendered in any way but, instead, must be fed into your own Pagination Component for rendering.\n\n💡 Looking for some Pagination Component inspiration? See [Integration Examples](#integration-examples) below to see how to use this with the JavaScript Framework Du Jour™.\n\n## API\n\n### `generate()`\n\nThe exposed `generate` function has the following API:\n\n```js\ngenerate(curPage, numPages, numPagesAtEdges = 2, numPagesAroundCurrent = 2, glue = '…');\n```\n\nParameters:\n\n- `curPage`: The current active page\n- `numPages`: The total number of pages\n- `numPagesAtEdges` _(default: 2)_: Number of pages to show on the outer edges.\n- `numPagesAroundCurrent` _(default: 2)_: Number of pages to show around the active page.\n- `glue` _(default: '…')_: The string to show when there's a gap\n\n### `generateFromObj()`\n\nThe `generateFromObj` function accepts one single `opts` object. Its members are all of the parameters described above. Default values are set where possible.\n\n```js\nconst { \n    curPage = 1,\n    numPages = 1,\n    numPagesAtEdges = 2,\n    numPagesAroundCurrent = 2,\n    glue = '…',\n} = opts;\n```\n\n## Principles\n\nThe algorithm is opinionated and follows these principles:\n\n- **Stable Output**\n\n  When generating a sequence, it will always generate the same amount of entries, for any `curPage` value. When viewing a page at the edge of a series, this can result in `numPagesAtEdges` being ignored.\n\n  For example: Instead of having `generate(2, 12, 1, 1)` return `01-[02]-03-..-12` _(5 entries)_, it will return `01-[02]-03-04-05-..-12` _(7 entries)_. This is a deliberate choice because `generate(7, 12, 1, 1)` will also return 7 entries: `01-..-06-[07]-08-..-12`.\n\n  With a stable amount of entries being generated, the output will also be visually stable when rendered on screen.\n\n- **Always include links to the edges**\n\n  The algorithm will always include links to the first and last page.\n\n  For Example: when looking at page 25 of 50, the algorithm will include a link to page 1 and page 50.\n\n- **No unnecessary gaps**\n\n  When the algorithm detects a gap that's only “1 item wide”, it will replace that gap with the actual number.\n\n  For Example: A foolish take on `generate(4, 9, 1, 1)`, would generate `01-..-03-[04]-05-..-09`. The algorithm corrects the first gap to `02` and will return `01-02-03-[04]-05-..-09` instead.\n\n## Integration Examples\n\n### React\n\n🔗 Try it online: [https://codepen.io/bramus/pen/NWaxNKQ](https://codepen.io/bramus/pen/NWaxNKQ)\n\n```jsx\nimport React from \"react\";\nimport ReactDOM from \"react-dom\";\nimport { generate } from \"@bramus/pagination-sequence\";\n\nconst BASE_URL = '#';\n\nconst PaginationEntry = ({ value, onEntryClick = null, label = null, title = null, isCurrent = false, isDisabled = false, ...props }) =\u003e {\n    label ??= value;\n    title ??= `Go to page ${value}`;\n\n    const onClick = (e) =\u003e {\n        e.stopPropagation();\n        e.preventDefault();\n        \n        e.target.blur();\n        \n        if (onEntryClick) {\n            onEntryClick(value);\n        }\n    }\n        \n    if (value == '…') {\n        return (\n            \u003cli data-pagination-ellipsis {...props}\u003e\u003cspan\u003e{label}\u003c/span\u003e\u003c/li\u003e\n        );\n    }\n\n    if (isDisabled) {\n        return (\n            \u003cli data-pagination-disabled {...props}\u003e\u003cspan\u003e{label}\u003c/span\u003e\u003c/li\u003e\n        );\n    }\n\n    if (isCurrent) {\n        props['data-pagination-current'] = true;\n    }\n\n    return (\n        \u003cli {...props}\u003e\n            \u003ca href={`${BASE_URL}/page/${value}`} title={title} onClick={onClick}\u003e{label}\u003c/a\u003e\n        \u003c/li\u003e\n    );\n}\n\nconst Pagination = ({ curPage, numPages, numPagesAtEdges = 2, numPagesAroundCurrent = 2, onEntryClick = null }) =\u003e {\n    const sequence = generate(curPage, numPages, numPagesAtEdges, numPagesAroundCurrent);\n    // console.log(sequence);\n\n    return (\n        \u003cul className=\"pagination\"\u003e\n            \u003cPaginationEntry data-pagination-first onEntryClick={onEntryClick} value={1} title=\"Go to First Page\" label=\"\u0026laquo;\" isDisabled={curPage === 1} /\u003e\n            \u003cPaginationEntry data-pagination-prev onEntryClick={onEntryClick} value={curPage-1} title=\"Go to Previous Page\" label=\"\u0026lsaquo;\" isDisabled={curPage === 1} /\u003e\n            {sequence.map((val, idx) =\u003e \n                \u003cPaginationEntry key={`page-${(val == '…') ? `…-${idx}` : val}`} onEntryClick={onEntryClick} value={val} isCurrent={val == curPage} /\u003e\n            )}\n            \u003cPaginationEntry data-pagination-next onEntryClick={onEntryClick} value={curPage+1} title=\"Go to Next Page\" label=\"\u0026rsaquo;\" isDisabled={curPage === numPages} /\u003e\n            \u003cPaginationEntry data-pagination-next onEntryClick={onEntryClick} value={numPages} title=\"Go to Last Page\" label=\"\u0026raquo;\" isDisabled={curPage === numPages} /\u003e\n        \u003c/ul\u003e\n    );\n}\n\nReactDOM.render(\n    \u003cPagination curPage={25} numPages={50} onEntryClick={(val) =\u003e { console.log(val)}} /\u003e,\n    document.getElementById('root')\n);\n```\n## License\n\n`@bramus/pagination-sequence` is released under the MIT public license. See the enclosed `LICENSE` for details.\n\n## Other Language Implementations\n\nLooking for an implementation in another programming language?\n\n- PHP: [https://gist.github.com/bramus/5d8f2e0269e57dff5136](https://gist.github.com/bramus/5d8f2e0269e57dff5136) _(The original, from 2014)_\n- _(submit a PR to add your own)_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbramus%2Fjs-pagination-sequence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbramus%2Fjs-pagination-sequence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbramus%2Fjs-pagination-sequence/lists"}