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

GitLab UI Components

import examples from './examples';

var description = "# Infinite Scroll\n\n<!-- STORY -->\n\n## Usage\n\nThe infinite scroll component wraps around a results list and emits a message\n(`bottomReached`) when the bottom of the viewport is reached, which should trigger\na re-fetching. The `gl-infinite-scroll` component expects its parent component to\nmanage the re-fetching.\n\nAdditionally it emits a `topReached` message when the top of the viewport is reached, which\ncan be useful to load items on top of the available data. If only `topReached` is present, the\nviewport will be scrolled to the bottom the first time this component is mounted.\n\n## Public methods\n\nUseful public methods you can call via `$refs`:\n\n- `.scrollUp()`: Scrolls to the top of the container.\n- `.scrollDown()`: Scrolls to the bottom of the container.\n- `.scrollTo({ top })`: Scrolls to a number of pixels along the Y axis of the container.\n\n## Implementation Example\n\nThis is how a full implementation would look like with paginated results from GitLab's\n`projects` API.\n\nIn the component's state, initialize a `pageInfo` object:\n\n```js\npageInfo: {\n  currentPage: 0,\n  nextPage: 0,\n  totalPages: 0,\n  totalResults: 0,\n}\n```\n\nWhen fetching for the first time, set the state with the header\ninformation in the mutations:\n\n```html\nVue.set(state.pageInfo, 'currentPage', parseInt(headers['X-Page'], 10));\nVue.set(state.pageInfo, 'nextPage', parseInt(headers['X-Next-Page'], 10));\nVue.set(state.pageInfo, 'totalPages', parseInt(headers['X-Total-Pages'], 10));\nVue.set(state.pageInfo, 'totalResults', parseInt(headers['X-Total'], 10));\n```\n\n_Note: There is a function you can use for parsing integers in headers in\nGitLab called `parseIntPagination` in `common/utils.js`_\n\nEvery time `bottomReached` happens, update the state in your mutations:\n\n```js\nstate.searchResults = state.searchResults.concat(results.data);\nVue.set(state.pageInfo, 'nextPage', parseInt(headers['X-Next-Page'],10));\nVue.set(state.pageInfo, 'totalPages', parseInt(headers['X-Total-Pages'],10));\n```\n\nUse the state to fetch the next page in the actions. In this case, the `Projects`\nAPI allows us to send in a `page` parameter to fetch a certain page from the\nlist of results.\n\n```js\nexport const fetchNextPage = ({ state, dispatch }) => {\n  if(state.pageInfo.currentPage < state.pageInfo.totalPages) {\n    Api.projects(searchQuery, { page: state.pageInfo.nextPage })\n      ...\n  }\n};\n```\n\n```html\n<script>\nexportDefault {\n  components: {\n    GlInfiniteScroll,\n  },\n  computed: {\n    ...mapState([\n      'pageInfo',\n      'searchResults',\n    ]),\n  },\n  methods: {\n    ...mapActions([\n      'fetchNextPage',\n    ]),\n    bottomReached() {\n      this.fetchNextPage();\n    },\n  },\n}\n</script>\n<template>\n  <gl-infinite-scroll\n    @bottomReached=\"bottomReached\"\n    :max-list-height=\"400\"\n    :fetched-items=\"searchResults.length\"\n    :total-items=\"totalResults\"\n  >\n    ...Results in a list, another component, etc ....\n  </gl-infinite-scroll>\n</template>\n```\n";

var infinite_scroll_documentation = {
  followsDesignSystem: true,
  description,
  examples,
  propsInfo: {
    totalItems: {
      additionalInfo: 'Total number of items available'
    },
    fetchedItems: {
      additionalInfo: 'Numbers of items fetched before scrolling'
    },
    maxListHeight: {
      additionalInfo: 'Max height of the list before the scrollbar appears'
    }
  },
  events: [{
    event: '@topReached',
    description: 'Emitted when item container is scrolled to the top'
  }, {
    event: '@bottomReached',
    description: 'Emitted when item container is scrolled to the bottom'
  }],
  slots: [{
    name: 'default',
    description: 'Footer of the list, appears below the items'
  }, {
    name: 'header',
    description: 'Header of the list, appears above the items'
  }, {
    name: 'items',
    description: 'List of items'
  }]
};

export default infinite_scroll_documentation;