npm package: @htmlbricks/hb-paginate
Description: Pagination bar with first/prev/next/last and nearby page buttons, optional “showing X–Y of total” text, configurable page-size input or select, and optional sort field and direction controls with i18n labels.
Latest version: 0.71.18

# hb-paginate

**Category:** utilities · **Tags:** utilities, navigation

## Description

Pagination controls (first / previous / numbered pages / next / last), optional “showing X–Y of total” text, optional page-size via **`hb-input-number`** or **`hb-input-select`**, and optional sort field + direction with i18n. Dispatches `pageChange`, `changePageSize`, and `changeSort`.

## Styling (Bulma)

The component bundles **Bulma 1.x** in the shadow root: **`form/shared`**, **`form/select`** (sort dropdown), and **`form/pagination`**, with theme defaults on `:host` (`--bulma-hb-def-*`). Set public **`--bulma-*`** on `body` or `:root` so they inherit onto the host and match the rest of the app. Relevant tokens include pagination, controls, text, and borders — see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).

**Shadow markup (simplified):**

- **`div.hb-paginate`** — single horizontal row: optional info/size block + **`nav.pagination`**.
- **`div.paginate-bar`** — rendered only when range text and/or page-size UI is needed (avoids extra flex gap when only pagination is shown).
- **`ul.pagination-list`** / **`button.pagination-link`** — Bulma pagination; list uses **`gap`** instead of doubled per-link horizontal margins.
- Sort UI: **`div.select.is-small`** + native **`select`**, and a direction **`button.pagination-link`**.

**Host-level overrides (optional):**

| Variable | Purpose |
|----------|---------|
| `--hb-paginate-height` | Fixed host height (default: `--bulma-control-height`, fallback `2.5rem`). |
| `--hb-paginate-bar-padding-inline-start` | Left inset for the info/size bar (default: `--bulma-pagination-item-padding-left`, fallback `0.5em`). |
| `--hb-paginate-list-gap` | Horizontal gap between pagination list items (default: half of `--bulma-pagination-item-margin`). |

## Custom element

`hb-paginate`

## Attributes (snake_case; string values in HTML)

- `id`, `style` (optional): strings.
- `page`, `pages` (required): current page index and total pages, as strings.
- `info` (optional): JSON string — `total`, `size`, `page_size_type` (`"number"` \| `"select"`), `page_size_options`, `sort_fields`, `sort_by`, `sort_direction`, `sort_disabled`, `sort_direction_disabled`, `sort_strict_direction`, `sort_default_value`, `sort_default_label`.
- `i18nlang` (optional): e.g. `en`, `it`.

## Events

- `pageChange`: `{ page: number; pages: number }`
- `changePageSize`: `{ page_size: number }`
- `changeSort`: `{ sort_by: string; sort_direction: string }`

## Usage notes

- **i18n:** Italian and English in metadata; set `i18nlang` accordingly.
- **`hb-table`:** while the table is in **`is_loading`**, **`hb-paginate`** remains mounted but hidden; an inline Bulma skeleton overlay mimics the bar. Use **`hb-paginate`** directly when you embed it outside the table.
- **Combined examples** (sort + page size): see `extra/docs.ts`.

## Types

```typescript
export type Component = {
  id?: string;
  style?: string;
  pages: number;
  page: number;
  info?: {
    total?: number;
    size?: number;
    page_size_type?: "number" | "select";
    page_size_options?: string;
    sort_fields?: { value: string; label?: string }[];
    sort_by?: string;
    sort_direction?: "asc" | "desc" | "default";
    sort_disabled?: boolean;
    sort_direction_disabled?: boolean;
    sort_strict_direction?: boolean;
    sort_default_value?: string;
    sort_default_label?: string;
  };
  i18nlang?: string;
};

export type Events = {
  pageChange: { page: number; pages: number };
  changePageSize: { page_size: number };
  changeSort: { sort_by: string; sort_direction: string };
};
```

## Minimal HTML example

```html
<hb-paginate page="0" pages="5" i18nlang="en"></hb-paginate>
```