kerosene
A pagination library for Ecto and Phoenix applications, supporting HTML and JSON output with customizable themes.
What is kerosene?
Kerosene is a pagination library for Elixir applications using the Ecto database wrapper and Phoenix web framework. It simplifies adding pagination to database queries and provides helpers to render pagination links in HTML templates and JSON responses. It solves the problem of manually implementing pagination logic in Phoenix applications.
Elixir developers building web applications with Phoenix and Ecto who need to paginate database queries efficiently. It's particularly useful for full-stack developers working on applications with list views or APIs that require paginated data.
Developers choose Kerosene for its tight integration with Ecto and Phoenix, reducing boilerplate code. Its unique selling point is the dual support for HTML and JSON pagination out-of-the-box, along with customizable themes and simple configuration.
Overview
Pagination for Ecto and Pheonix.
Use Cases
Best For
- Adding pagination to Ecto queries in Phoenix applications
- Building JSON APIs that require paginated responses
- Creating list views with Bootstrap or Foundation-styled pagination links
- Implementing 'Prev/Next' only pagination for minimal interfaces
- Reducing boilerplate code for pagination in Elixir web projects
- Developing single-page applications that consume paginated Elixir APIs
Not Ideal For
- Applications requiring cursor-based pagination for real-time updates or infinite scrolling
- Elixir projects not using the Phoenix web framework or Ecto for database access
- Teams needing highly customized pagination UI beyond the provided Bootstrap and Foundation themes
- Microservices or APIs that require pagination without the full Phoenix view layer for lightweight setups
Pros & Cons
Pros
Integrates directly with Ecto's Repo via a simple `Repo.paginate/2` function, reducing boilerplate code as shown in the usage example for paginating queries.
Provides built-in helpers for both HTML templates and JSON responses, making it versatile for full-stack applications and APIs, with examples for rendering pagination links in each format.
Offers flexible configuration for items per page and a minimalist 'simple mode' for prev/next links, easily adjustable via application config to suit different UI needs.
Includes pre-styled pagination links for popular CSS frameworks like Bootstrap and Foundation, with theme selection configurable in config.exs for quick setup.
Cons
Tightly coupled with Ecto and Phoenix, making it unsuitable for projects using other Elixir databases or web frameworks, limiting its applicability in broader contexts.
Only supports Bootstrap and Foundation themes out of the box, requiring additional effort for custom CSS or integration with other styling frameworks not mentioned in the README.
Relies on offset/limit pagination by default, which may not scale well for large datasets or support advanced features like cursor-based pagination without manual extension.
Frequently Asked Questions
Related Projects
plugCompose web applications with functions
surfaceA server-side rendering component library for Phoenix
commandedUse Commanded to build Elixir CQRS/ES applications
ex_adminExAdmin is an auto administration package for Elixir and the Phoenix Framework
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.