@gitlab/ui/dist/components/base/keyset_pagination/keyset_pagination.documentation.js

GitLab UI Components

import examples from './examples';

var keyset_pagination = "# Keyset Pagination\n\nPagination is used to help users parse a large number of items on a page,\nwhenever there are too many results to show at once. Pagination breaks up\nresults into several pages with controls for navigating forward and backward, or\nto a specific page.\n\n## Usage\n\nThe simplest way to use `GlKeysetPagination` with a paginated GraphQL response\nis to `v-bind` to the\n[`PageInfo`](https://docs.gitlab.com/ee/api/graphql/reference/#pageinfo) type\nreturned by the endpoint:\n\n```html\n<gl-keyset-pagination v-bind=\"pageInfo\" />\n```\n\nThis is possible because the default field names of the `PageInfo` type align\nwith the `props` of this component.\n\n## Dos and don'ts\n\n**✅ Do** provide the `prevText` and `nextText` props with translatable strings.\nThe default strings (\"Prev\" and \"Next\") are hardcoded in this component and\ncan't be translated.\n\nExample:\n\n```html\n<gl-keyset-pagination v-bind=\"pageInfo\" :prev-text=\"__('Prev')\" :next-text=\"__('Next')\" />\n```\n\n**✅ Do** use this component for paginating GraphQL requests<sup>1</sup> (or any\nendpoint that uses keyset pagination).\n\n**❌ Don't** use this component for paginating REST requests<sup>1</sup> (or any\nendpoint that uses offset pagination).\n\nFor offset pagination, use the [`GlPagination`\ncomponent](/?path=/story/base-pagination--default) instead.\n\nFor more information on the difference between offset and keyset pagination see\n[our documentation on GraphQL\npagination](https://docs.gitlab.com/ee/development/graphql_guide/pagination.html).\n\n<small><sup>1</sup>There's no intrinsic reason why GraphQL endpoints can't\nsupport offset pagination (in fact, [the official\ndocumentation](https://graphql.org/learn/pagination/#pagination-and-edges) shows\nan example offset pagination implementation) or why REST endpoints can't support\nkeyset pagination. This is simply how we've chosen to implement our REST and\nGraphQL endpoints at GitLab.</small>\n\n## Pajamas reference\n\n<https://design.gitlab.com/components/pagination>\n";

var description = /*#__PURE__*/Object.freeze({
  __proto__: null,
  'default': keyset_pagination
});

var keyset_pagination_documentation = {
  description,
  followsDesignSystem: true,
  bootstrapComponent: false,
  examples,
  propsInfo: {
    hasPreviousPage: {
      type: Boolean,
      required: false,
      default: false,
      additionalInfo: 'Whether or not the "Prev" button should be enabled'
    },
    hasNextPage: {
      type: Boolean,
      required: false,
      default: false,
      additionalInfo: 'Whether or not the "Next" button should be enabled'
    },
    startCursor: {
      type: String,
      required: false,
      default: null,
      additionalInfo: 'A cursor that points to the first item in the current page. Will be passed as an event parameter when the "prev" event is fired.'
    },
    endCursor: {
      type: String,
      required: false,
      default: null,
      additionalInfo: 'A cursor that points to the last item in the current page. Will be passed as an event parameter when the "next" event is fired.'
    },
    prevText: {
      type: String,
      required: false,
      default: 'Prev',
      additionalInfo: 'The text that will be rendered inside the "Prev" button. It\'s important to provide this parameter since the default text is not translatable.'
    },
    prevButtonLink: {
      type: String,
      required: false,
      default: null,
      additionalInfo: 'A link that will be used as the "Prev" button\'s "href" attribute. If provided, the "Prev" button renders as a link button; otherwise, it is rendered as a regular button.'
    },
    nextText: {
      type: String,
      required: false,
      default: 'Next',
      additionalInfo: 'The text that will be rendered inside the "Next" button. It\'s important to provide this parameter since the default text is not translatable.'
    },
    nextButtonLink: {
      type: String,
      required: false,
      default: null,
      additionalInfo: 'A link that will be used as the "Next" button\'s "href" attribute. If provided, the "Next" button renders as a link button; otherwise, it is rendered as a regular button.'
    },
    disabled: {
      type: Boolean,
      required: false,
      default: false,
      additionalInfo: 'Whether or not both buttons should be disabled (regardless of the "hasPreviousPage" and "hasNextPage" values).'
    }
  },
  events: [{
    event: 'prev',
    description: 'Emitted when the "Prev" button is clicked',
    args: [{
      arg: 'startCursor',
      description: 'A cursor that points to the first item in the current page.'
    }]
  }, {
    event: 'next',
    description: 'Emitted when the "Next" button is clicked',
    args: [{
      arg: 'endCursor',
      description: 'A cursor that points to the last item in the current page'
    }]
  }],
  slots: [{
    name: 'previous-button-content',
    description: 'Used to customize the appearance of the "Prev" button'
  }, {
    name: 'next-button-content',
    description: 'Used to customize the appearance of the "Next" button'
  }]
};

export default keyset_pagination_documentation;