Pagination

Select a page from a range, or with "next" and "previous" controls.

The Pagination component has no restrictions on what type of data or visuals it is used with since it strictly handles the visual enumeration and controls based on totalItemCount and itemsPerPage values.

Pagination includes an onChange event that emits the updated page number which can then be used to alter the data displayed.

The Pagination component will not display if the totalItemCount is less than the count needed to create more than one page.

Expanded Pagination

The default variant for Pagination is expanded which means a list of buttons to navigate between available pages will be displayed and is recommended for large datasets.

The only required property is totalItemCount which will be used with the default itemsPerPage of 10 to calculate the total number of pages.

In the live demo below, you can experiment with updating the itemsPerPage values as well as the activePage to see how it affects the display of data.

() => {
  const itemsPerPage = 10;
  const activePage = 10;

  const countries = useMockArray();
  const [listItems, setListItems] = React.useState(countries.slice(0, itemsPerPage));
  const [currPage, setCurrPage] = React.useState(activePage);
  const dataContainerRef = React.createRef();

  const handlePagination = (page) => {
    const start = (page - 1) * itemsPerPage;
    const end = start + itemsPerPage;
    setListItems(countries.slice(start, end));
    setCurrPage(page);

    if (dataContainerRef.current) {
      dataContainerRef.current.focus();
    }
  };

  return (
    <Grid container justify="center" spacing={2}>
      <Grid item xs={12}>
        <RootRef rootRef={dataContainerRef}>
          <List dense tabIndex={-1} style={{ outline: 'none' }}>
            {listItems.map((country, index) => {
              const itemNumber =
                currPage === 1 ? index + 1 : (currPage - 1) * itemsPerPage + (index + 1);
              return (
                <ListItem key={country} button>
                  <ListItemText primary={`${itemNumber}: ${country}`} />
                </ListItem>
              );
            })}
          </List>
        </RootRef>
      </Grid>
      <Grid item xs="auto">
        <Pagination
          totalItemCount={countries.length}
          itemsPerPage={itemsPerPage}
          activePage={currPage}
          onChange={handlePagination}
        />
      </Grid>
    </Grid>
  );
};

() => {
  const itemsPerPage = 10;
  const activePage = 10;

  const countries = useMockArray();
  const [listItems, setListItems] = React.useState(countries.slice(0, itemsPerPage));
  const [currPage, setCurrPage] = React.useState(activePage);
  const dataContainerRef = React.createRef();

  const handlePagination = (page) => {
    const start = (page - 1) * itemsPerPage;
    const end = start + itemsPerPage;
    setListItems(countries.slice(start, end));
    setCurrPage(page);

    if (dataContainerRef.current) {
      dataContainerRef.current.focus();
    }
  };

  return (
    <Grid container justify="center" spacing={2}>
      <Grid item xs={12}>
        <RootRef rootRef={dataContainerRef}>
          <List dense tabIndex={-1} style={{ outline: 'none' }}>
            {listItems.map((country, index) => {
              const itemNumber =
                currPage === 1 ? index + 1 : (currPage - 1) * itemsPerPage + (index + 1);
              return (
                <ListItem key={country} button>
                  <ListItemText primary={`${itemNumber}: ${country}`} />
                </ListItem>
              );
            })}
          </List>
        </RootRef>
      </Grid>
      <Grid item xs="auto">
        <Pagination
          totalItemCount={countries.length}
          itemsPerPage={itemsPerPage}
          activePage={currPage}
          onChange={handlePagination}
        />
      </Grid>
    </Grid>
  );
};

User Controlled `itemsPerPage`

You may provide an additional control to allow the user to update the itemsPerPage.

The following shows how to associate a control for updating the number of items displayed within the pagination list. The placement and type of control should be determined based on your implementation context.

() => {
  const countries = useMockArray('countries', 150);
  const [itemsPerPage, setItemsPerPage] = React.useState(10);
  const [listItems, setListItems] = React.useState(countries.slice(0, itemsPerPage));
  const [currPage, setCurrPage] = React.useState(1);
  const dataContainerRef = React.createRef();

  React.useEffect(() => {
    updatePagination();
  }, [currPage, itemsPerPage]);

  const updatePagination = () => {
    const pageIndex = currPage === 1 ? currPage : currPage - 1;
    const start = pageIndex * itemsPerPage;
    const end = start + itemsPerPage;

    setListItems(countries.slice(start, end));
  };

  const handleItemsPerPage = (event) => {
    const { value } = event.target;

    setCurrPage(1);
    setItemsPerPage(parseInt(value));
  };

  const handlePagination = (page) => {
    setCurrPage(page);

    if (dataContainerRef.current) {
      dataContainerRef.current.focus();
    }
  };

  return (
    <Grid container justify="center" spacing={2}>
      <Grid item xs={12} md={4} margin={{ left: 'auto' }}>
        <FormControl variant="outlined" fullWidth>
          <InputLabel htmlFor="itemsperpage">Items Per Page</InputLabel>
          <Select
            native
            variant="outlined"
            name="itemsPerPage"
            labelWidth={140}
            inputProps={{
              id: 'itemsperpage',
            }}
            onChange={handleItemsPerPage}
            value={itemsPerPage}
          >
            {[10, 25, 50, 100].map((option) => {
              return (
                <option key={option} value={option}>
                  {option}
                </option>
              );
            })}
          </Select>
        </FormControl>
      </Grid>
      <Grid item xs={12}>
        <RootRef rootRef={dataContainerRef}>
          <List dense tabIndex={-1} style={{ outline: 'none' }}>
            {listItems.map((country, index) => {
              const itemNumber =
                currPage === 1 ? index + 1 : (currPage - 1) * itemsPerPage + (index + 1);
              return (
                <ListItem key={country} button>
                  <ListItemText primary={`${itemNumber}: ${country}`} />
                </ListItem>
              );
            })}
          </List>
        </RootRef>
      </Grid>
      <Grid item xs="auto">
        <Pagination
          totalItemCount={countries.length}
          itemsPerPage={itemsPerPage}
          activePage={currPage}
          onChange={handlePagination}
        />
      </Grid>
    </Grid>
  );
};

() => {
  const countries = useMockArray('countries', 150);
  const [itemsPerPage, setItemsPerPage] = React.useState(10);
  const [listItems, setListItems] = React.useState(countries.slice(0, itemsPerPage));
  const [currPage, setCurrPage] = React.useState(1);
  const dataContainerRef = React.createRef();

  React.useEffect(() => {
    updatePagination();
  }, [currPage, itemsPerPage]);

  const updatePagination = () => {
    const pageIndex = currPage === 1 ? currPage : currPage - 1;
    const start = pageIndex * itemsPerPage;
    const end = start + itemsPerPage;

    setListItems(countries.slice(start, end));
  };

  const handleItemsPerPage = (event) => {
    const { value } = event.target;

    setCurrPage(1);
    setItemsPerPage(parseInt(value));
  };

  const handlePagination = (page) => {
    setCurrPage(page);

    if (dataContainerRef.current) {
      dataContainerRef.current.focus();
    }
  };

  return (
    <Grid container justify="center" spacing={2}>
      <Grid item xs={12} md={4} margin={{ left: 'auto' }}>
        <FormControl variant="outlined" fullWidth>
          <InputLabel htmlFor="itemsperpage">Items Per Page</InputLabel>
          <Select
            native
            variant="outlined"
            name="itemsPerPage"
            labelWidth={140}
            inputProps={{
              id: 'itemsperpage',
            }}
            onChange={handleItemsPerPage}
            value={itemsPerPage}
          >
            {[10, 25, 50, 100].map((option) => {
              return (
                <option key={option} value={option}>
                  {option}
                </option>
              );
            })}
          </Select>
        </FormControl>
      </Grid>
      <Grid item xs={12}>
        <RootRef rootRef={dataContainerRef}>
          <List dense tabIndex={-1} style={{ outline: 'none' }}>
            {listItems.map((country, index) => {
              const itemNumber =
                currPage === 1 ? index + 1 : (currPage - 1) * itemsPerPage + (index + 1);
              return (
                <ListItem key={country} button>
                  <ListItemText primary={`${itemNumber}: ${country}`} />
                </ListItem>
              );
            })}
          </List>
        </RootRef>
      </Grid>
      <Grid item xs="auto">
        <Pagination
          totalItemCount={countries.length}
          itemsPerPage={itemsPerPage}
          activePage={currPage}
          onChange={handlePagination}
        />
      </Grid>
    </Grid>
  );
};

Basic Pagination

Use of variant="basic" is recommended for short datasets, generally less than 50 items which equates to 5 pages using the default itemsPerPage of 10.

Basic Pagination offers simple "previous" and "next" controls with a dynamically updating label that is also announced via aria-live.

() => {
  const itemsPerPage = 10;
  const activePage = 1;

  const animals = useMockArray('animals', 48);
  const [listItems, setListItems] = React.useState(animals.slice(0, itemsPerPage));
  const [currPage, setCurrPage] = React.useState(activePage);
  const dataContainerRef = React.createRef();

  const handlePagination = (page) => {
    const start = (page - 1) * itemsPerPage;
    const end = start + itemsPerPage;
    setListItems(animals.slice(start, end));
    setCurrPage(page);

    if (dataContainerRef.current) {
      dataContainerRef.current.focus();
    }
  };

  return (
    <Grid container justify="center" spacing={2}>
      <Grid item xs={12}>
        <RootRef rootRef={dataContainerRef}>
          <List dense tabIndex={-1} style={{ outline: 'none' }}>
            {listItems.map((animal, index) => {
              const itemNumber =
                currPage === 1 ? index + 1 : (currPage - 1) * itemsPerPage + (index + 1);
              return (
                <ListItem key={animal} button>
                  <ListItemText primary={`${itemNumber}: ${animal}`} />
                </ListItem>
              );
            })}
          </List>
        </RootRef>
      </Grid>
      <Grid item xs="auto">
        <Pagination
          variant="basic"
          totalItemCount={animals.length}
          itemsPerPage={itemsPerPage}
          activePage={activePage}
          onChange={handlePagination}
        />
      </Grid>
    </Grid>
  );
};

() => {
  const itemsPerPage = 10;
  const activePage = 1;

  const animals = useMockArray('animals', 48);
  const [listItems, setListItems] = React.useState(animals.slice(0, itemsPerPage));
  const [currPage, setCurrPage] = React.useState(activePage);
  const dataContainerRef = React.createRef();

  const handlePagination = (page) => {
    const start = (page - 1) * itemsPerPage;
    const end = start + itemsPerPage;
    setListItems(animals.slice(start, end));
    setCurrPage(page);

    if (dataContainerRef.current) {
      dataContainerRef.current.focus();
    }
  };

  return (
    <Grid container justify="center" spacing={2}>
      <Grid item xs={12}>
        <RootRef rootRef={dataContainerRef}>
          <List dense tabIndex={-1} style={{ outline: 'none' }}>
            {listItems.map((animal, index) => {
              const itemNumber =
                currPage === 1 ? index + 1 : (currPage - 1) * itemsPerPage + (index + 1);
              return (
                <ListItem key={animal} button>
                  <ListItemText primary={`${itemNumber}: ${animal}`} />
                </ListItem>
              );
            })}
          </List>
        </RootRef>
      </Grid>
      <Grid item xs="auto">
        <Pagination
          variant="basic"
          totalItemCount={animals.length}
          itemsPerPage={itemsPerPage}
          activePage={activePage}
          onChange={handlePagination}
        />
      </Grid>
    </Grid>
  );
};

Pagination

Expanded Pagination

User Controlled itemsPerPage

Basic Pagination

Properties

<Pagination />

User Controlled `itemsPerPage`