Pagination

The Pagination component is responsive and flexible way to indicate a series of related content exists across multiple pages. It can be used to displays data in paged format and provides navigation between pages. The root element is a HTML native nav element to indicate a navigation section. The component uses the Button component for the navigation elements.

Examples

Base

The component uses three main properties: the current prop,which is two-way bindable and shows the active page; the total prop, which defines the total number of pages; and the per-page prop, which is used to define the number of elements per page. The current page is marked with aria-current set to "page" as well. In addition, since pages likely have more than one navigation section, it is advisable to provide a descriptive aria-label for the nav element to reflect its purpose.

Show code

HTML

<section>
    <o-pagination v-model:current="current" :total="100" :per-page="10" />

    <p><b>Current:</b> {{ current }}</p>
</section>

JS

import { ref } from "vue";

const current = ref(2);

Simple

The component can be displayed in a simplified state by using the simple prop. This simplified representation uses aria-live="polite" to notify the screen reader of changes to the pagination state.

Show code

HTML

<section>
    <o-pagination
        v-model:current="current"
        :total="100"
        :per-page="10"
        simple />

    <p><b>Current:</b> {{ current }}</p>
</section>

JS

import { ref } from "vue";

const current = ref(10);

Positions

The compoponent can be positioned by the position prop.

Show code

HTML

<section class="odocs-spaced">
    <p>
        <o-pagination
            :current="2"
            :total="100"
            :per-page="10"
            position="left" />
    </p>
    <p>
        <o-pagination
            :current="2"
            :total="100"
            :per-page="10"
            position="centered" />
    </p>
    <p>
        <o-pagination
            :current="2"
            :total="100"
            :per-page="10"
            position="right" />
    </p>
</section>

Sizes

The component can be displayed in different sizes using the size prop.

Show code

HTML

<section class="odocs-spaced">
    <p>
        <o-pagination
            :current="2"
            :total="100"
            :per-page="10"
            size="small" />
    </p>
    <p>
        <o-pagination :current="2" :total="100" :per-page="10" />
    </p>
    <p>
        <o-pagination
            :current="2"
            :total="100"
            :per-page="10"
            size="medium" />
    </p>
    <p>
        <o-pagination
            :current="2"
            :total="100"
            :per-page="10"
            size="large" />
    </p>
</section>

Disabled

Use thedisabled prop to prevent buttons from being clicked.

Show code

HTML

<section>
    <o-pagination :total="100" :per-page="10" disabled />
</section>

Customise

Show code

HTML

<section>
    <o-field grouped multiline>
        <o-field label="Total">
            <o-input v-model="total" type="number" number />
        </o-field>
        <o-field label="Items per page">
            <o-input v-model="perPage" type="number" number />
        </o-field>
    </o-field>
    <o-field grouped multiline>
        <o-field label="Show buttons before current">
            <o-input v-model="rangeBefore" type="number" number min="0" />
        </o-field>
        <o-field label="Show buttons after current">
            <o-input v-model="rangeAfter" type="number" number min="0" />
        </o-field>
    </o-field>
    <o-field grouped multiline>
        <o-field label="Position">
            <o-select v-model="position">
                <option value="left">left</option>
                <option value="centered">centered</option>
                <option value="right">right</option>
            </o-select>
        </o-field>
        <o-field label="Size">
            <o-select v-model="size">
                <option value="">default</option>
                <option value="small">small</option>
                <option value="medium">medium</option>
                <option value="large">large</option>
            </o-select>
        </o-field>
        <o-field label="Previous icon">
            <o-select v-model="prevIcon">
                <option value="chevron-left">Chevron</option>
                <option value="arrow-left">Arrow</option>
            </o-select>
        </o-field>
        <o-field label="Next icon">
            <o-select v-model="nextIcon">
                <option value="chevron-right">Chevron</option>
                <option value="arrow-right">Arrow</option>
            </o-select>
        </o-field>
    </o-field>
    <o-field grouped>
        <o-switch v-model="isSimple" label="Simple" />
        <o-switch v-model="isRounded" label="Rounded" />
        <o-switch v-model="isDisabled" label="Disabled" />
    </o-field>

    <hr />

    <o-pagination
        v-model:current="current"
        :total="total"
        :per-page="perPage"
        :range-before="rangeBefore || 0"
        :range-after="rangeAfter || 0"
        :position="position"
        :size="size"
        :disabled="isDisabled"
        :simple="isSimple"
        :rounded="isRounded"
        :icon-prev="prevIcon"
        :icon-next="nextIcon" />

    <p><b>Current:</b> {{ current }}</p>
</section>

JS

import { ref } from "vue";

const rangeBefore = ref(3);
const rangeAfter = ref(1);
const isSimple = ref(false);
const isRounded = ref(false);
const isDisabled = ref(false);
const prevIcon = ref("chevron-left");
const nextIcon = ref("chevron-right");
const total = ref(200);
const current = ref(10);
const perPage = ref(10);
const position = ref<"left" | "centered" | "right">("left");
const size = ref("");

Templates

The component can be further customised by using template slots to override specific buttons.

Show code

HTML

<section>
    <o-pagination v-model:current="current" :total="200" :per-page="10">
        <template #default="props">
            <o-button
                :label="convertToRoman(props.number)"
                :disabled="props.isCurrent"
                :aria-label="props.ariaLabel"
                :aria-current="props.isCurrent"
                @click="props.onClick" />
        </template>

        <template #previous="props">
            <o-button
                label="Previous"
                :disabled="props.isCurrent"
                :aria-label="props.ariaLabel"
                @click="props.onClick" />
        </template>

        <template #next="props">
            <o-button
                label="Next"
                :disabled="props.isCurrent"
                :aria-label="props.ariaLabel"
                @click="props.onClick" />
        </template>
    </o-pagination>
</section>

JS

import { ref } from "vue";

const basicRomanNumeral = ref([
    "",
    "I",
    "II",
    "III",
    "IV",
    "V",
    "VI",
    "VII",
    "VIII",
    "IX",
    "",
    "X",
    "XX",
    "XXX",
    "XL",
    "L",
    "LX",
    "LXX",
    "LXXX",
    "XC",
    "",
    "C",
    "CC",
    "CCC",
    "CD",
    "D",
    "DC",
    "DCC",
    "DCCC",
    "CM",
    "",
    "M",
    "MM",
    "MMM",
]);

const current = ref(10);

function convertToRoman(num: number): string {
    const numArray = num.toString().split("");
    const base = numArray.length;
    let count = base - 1;
    return numArray.reduce((roman, digit) => {
        const digitRoman = basicRomanNumeral.value[+digit + count * 10];
        const result = roman + digitRoman;
        count -= 1;
        return result;
    }, "");
}

Pagination Component

A responsive and flexible paginator navigation.

<o-pagination></o-pagination>

Props

Prop name	Description	Type	Values	Default
ariaCurrentLabel	Accessibility label for the current page button.	string	-	From config: pagination: {   ariaCurrentLabel: "Current page" }
ariaNextLabel	Accessibility label for the next page button.	string	-	From config: pagination: {   ariaNextLabel: "Next page" }
ariaPageLabel	Accessibility label for the page button.	string	-	From config: pagination: {   ariaPageLabel: "Page" }
ariaPreviousLabel	Accessibility label for the previous page button.	string	-	From config: pagination: {   ariaPreviousLabel: "Previous page" }
buttonTag	Pagination button tag name	DynamicComponent	-	From config: pagination: {   buttonTag: PlainButton }
current	deprecated - will be renamed to modelValue Current page number, use v-model:current to make it two-way binding	number	-	1
disabled	Buttons will be disabled	boolean	-	false
iconNext	Icon to use for next button	string	-	From config: pagination: {   iconNext: "chevron-right" }
iconPack	Icon pack to use	string	mdi, fa, fas and any other custom icon pack	From config: pagination: {   iconPack: undefined }
iconPrev	Icon to use for previous button	string	-	From config: pagination: {   iconPrev: "chevron-left" }
mobileBreakpoint	Mobile breakpoint as max-width value	string	-	From config: pagination: {   mobileBreakpoint: undefined }
override	Override existing theme classes completely	boolean	-
perPage	Items count for each page	number | string	-	From config: pagination: {   perPage: 20 }
position	Buttons position order	"centered" | "left" | "right"	centered, right, left	From config: pagination: {   position: "right" }
rangeAfter	Number of pagination items to show after current page	number	-	1
rangeBefore	Number of pagination items to show before current page	number	-	1
rounded	Enable rounded button style	boolean	-	From config: pagination: {   rounded: false }
simple	Enable simple style	boolean	-	From config: pagination: {   simple: false }
size	Pagination size	string	small, medium, large	From config: pagination: {   size: undefined }
total	Total count of items	number	-

Events

Event name	Properties	Description
update:current	value number - updated current prop	current prop two-way binding
change	value number - current value	on current change event
next	event Event - native click event value number - new current value	on next button event click
previous	event Event - native click event value number - new current value	on previous button event

Slots

Name	Description	Bindings
previous	Define a custom previous button here	number number - page number isCurrent boolean - if page is current onClick (event: Event): void - click handler ariaLabel string - aria-label attribute
next	Define a custom next button here	number number - page number isCurrent boolean - if page is current onClick (event: Event): void - click handler ariaLabel string - aria-label attribute
default	Define a custom pagination button here	number number - page number isCurrent boolean - if page is current onClick (event: Event): void - click handler ariaLabel string - aria-label attribute

Class Inspector

Classes applied to the element:

➜ Want to know how does the Class Inspector work?

Class props inspector is useful to see class props you want to use to customize Oruga components and how they change a component. You can click on Inspect button to find the exact element where a specific class prop acts.

In the Class props inspector there are other columns:

Class prop

This column contains the name of the Class prop you want to inspect.
If you find a name with a link ( ▷ classPropName) this refers to a subitem (e.g. Dropdown Item in Dropdown).

Description

This column contains the description of the Class prop you want to inspect.
👉 This icon indicates some warning, e.g. this Class prop is visible only on mobile.

Props

This column contains a list of props that activate the class, e.g. if a class prop contains disabled prop it means that only when the component has disabled prop.

Suffixes

This column contains all the possible suffixes that you'll receive if you use a function to customize your Class prop.

Class prop	Description	Props	Suffixes
rootClass	Class of the root element.
mobileClass	Class of the root element when on mobile. 👉 Switch to mobile view to see it in action!
positionClass	Class of the root element with position.	position	centered right left
sizeClass	Class for the root elemnt with size.	size	small medium large
simpleClass	Class of the root element when in `simple` mode.	simple
infoClass	Class of the page info in `simple` mode.	simple
listClass	Class of the items list element.
listItemClass	Class of the list item element.
ellipsisClass	Class of the ellipsis element.
buttonClass	Class of the button element.
roundedClass	Class of the button element when rounded.	rounded
buttonCurrentClass	Class of the current button element.
buttonPrevClass	Class of the prev button element.
buttonNextClass	Class of the next button element.
buttonDisabledClass	Class of the prev or next button when disabled.
buttonClasses	Classes to apply on the internal button component. More details here.

Sass Variables

Current theme ➜ Oruga

SASS Variable	Default
$pagination-spacer	calc(0.5 * h.useVar("control-spacer"))
$pagination-disabled-opacity	h.useVar("control-disabled-opacity")
$pagination-ellipsis-color	h.useVar("grey-light")
$pagination-button-color	h.useVar("font-color")
$pagination-button-font-size	h.useVar("font-size")
$pagination-button-font-weight	h.useVar("font-weight")
$pagination-button-line-height	h.useVar("line-height")
$pagination-button-height	2.25em
$pagination-button-min-width	$pagination-button-height
$pagination-button-padding	h.useVar("control-spacer")
$pagination-button-box-shadow	none
$pagination-button-border-width	h.useVar("control-border-width")
$pagination-button-border-color	h.useVar("control-border-color")
$pagination-button-border-style	solid
$pagination-button-border-radius	h.useVar("border-radius")
$pagination-button-border-radius-rounded	h.useVar( "border-radius-rounded")
$pagination-button-background-color	h.useVar( "control-brackground-color")
$pagination-button-hover-color	$pagination-button-color
$pagination-button-hover-background-color	$pagination-button-background-color
$pagination-button-hover-border-color	$pagination-button-border-color
$pagination-button-current-color	h.useVar("white")
$pagination-button-current-background-color	h.useVar("primary")
$pagination-button-current-border-color	h.useVar("primary")

See ➜ 📄 SCSS file

Current theme ➜ Bulma

The theme does not have any custom variables for this component.

Current theme ➜ Bootstrap

SASS Variable	Default
$pagination-items-spacer	0.5rem

See ➜ 📄 SCSS file