Creating a custom view pager in Drupal.

@ViewsPager is a plugin type provided by the Drupal core Views module. and we can utilize that annotation to define a custom view pager.

Here is an example.

<?php

namespace Drupal\my_module\Plugin\views\pager;

use Drupal\Core\Pager\PagerManagerInterface;
use Drupal\Core\Pager\PagerParametersInterface;
use Drupal\views\Plugin\views\pager\Full;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * Plugin to provide an alternate pager to support featured item.
 *
 * @ingroup views_pager_plugins
 *
 * @ViewsPager(
 *   id = "alternate_pager",
 *   title = @Translation("Alternate Pager"),
 *   short_title = @Translation("Alternate Pager"),
 *   help = @Translation("An alternate pager to support featured item."),
 *   theme = "pager",
 *   register_theme = FALSE
 * )
 */
class AlternatePager extends Full {

  /**
   * Display helper service.
   *
   * @var \Drupal\my_module\DisplayHelper
   */
  protected DisplayHelper $displayHelper;

  /**
   * {@inheritdoc}
   */
  public function __construct(array                    $configuration, $plugin_id, $plugin_definition,
                              PagerManagerInterface    $pager_manager,
                              PagerParametersInterface $pager_parameters,
                              DisplayHelper            $displayHelper) {
    parent::__construct(
      $configuration,
      $plugin_id,
      $plugin_definition,
      $pager_manager,
      $pager_parameters
    );
    $this->displayHelper = $displayHelper;
  }

  /**
   * {@inheritdoc}
   */
  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
    return new static(
      $configuration,
      $plugin_id,
      $plugin_definition,
      $container->get('pager.manager'),
      $container->get('pager.parameters'),
      $container->get('display.helper'),
    );
  }

  /**
   * {@inheritdoc}
   */
  public function query() {
    parent::query();

    if (!$this->displayHelper->hasFeaturedItem()) {
      return;
    }

    $items_per_page = $this->getItemsPerPage() ?? 6;

    if ($this->getCurrentPage()) {
      $offset = $this->view->query->offset;
      $offset = $offset % $items_per_page === 0 ? $offset - 1 : $offset;
      // Skip first item as we are showing it as featured item.
      $this->view->query->setOffset($offset);
    }
    else {
      $this->view->query->setLimit($items_per_page - 1);
    }
  }

}

In the example provided above, we are not including any custom options or form fields. However, if we wish to add them, we can utilize the defineOptions() and buildOptionsForm() functions of the base plugin. Here's an example:

<?php

  /**
   * {@inheritdoc}
   */
  protected function defineOptions() {
    $options = parent::defineOptions();
    $options['skip_if_featured'] = ['default' => true];

    return $options;
  }

  /**
   * {@inheritdoc}
   */
  public function buildOptionsForm(&$form, FormStateInterface $form_state) {
    parent::buildOptionsForm($form, $form_state);

    $form['skip_if_featured'] = [
      '#type' => 'checkbox',
      '#title' => $this->t('Skip first item if featured item is loaded.'),
      '#default_value' => $this->options['skip_if_featured'],
    ];
  }