Step Scroller

⭐Star

👑Pioneer

A container component specifically designed for displaying a large number of elements within a limited row or column space. It supports both horizontal and vertical step-based scrolling, mouse wheel operations, and is deeply optimized for form components like TuiRadio and TuiCheckbox.

Basic Usage

The most basic usage is to wrap a series of elements within TuiStepScroller. The component will automatically calculate the available space and provide pagination controls.

<script setup>
import { ref } from 'vue'

const items = ref(Array.from({ length: 20 }, (_, i) => i + 1))
</script>

<template>
  <div style="height: 60px;">
    <TuiStepScroller>
      <div v-for="item in items" :key="item" class="demo-box">
        {{ item }}
      </div>
    </TuiStepScroller>
  </div>
</template>

<style scoped>
.demo-box {
  width: 50px;
  height: 40px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: var(--tui-bg-color);
  border: 1px solid var(--tui-border-color);
  border-radius: 4px;
}
</style>

Vertical Scrolling

Set direction to 'v' to enable vertical scrolling mode. Please ensure that the parent container or the component itself has a defined height.

<template>
  <div style="height: 300px; width: 100px;">
    <TuiStepScroller direction="v">
      <div v-for="i in 20" :key="i" class="vertical-item">
        Item {{ i }}
      </div>
    </TuiStepScroller>
  </div>
</template>

<style scoped>
.vertical-item {
  height: 40px;
  width: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  border-bottom: 1px solid #eee;
}
</style>

Adapting to Form Components

TuiStepScroller features specific layout optimizations for TuiRadio and TuiCheckbox. When displaying a large number of options via the scroller, it maintains a neat arrangement.

It is recommended to use the border property to control the divider style.

<script setup>
import { ref } from 'vue'

const radioVal = ref(1)
const checkVal = ref([])
</script>

<template>
  <div style="height: 50px; margin-bottom: 20px;">
    <TuiStepScroller border="auto">
      <TuiRadio v-model="radioVal" appearance="button">
        <TuiRadioItem v-for="i in 15" :key="i" :value="i">
          Option {{ i }}
        </TuiRadioItem>
      </TuiRadio>
    </TuiStepScroller>
  </div>

  <div style="height: 200px; width: 150px;">
    <TuiStepScroller direction="v" border="none">
      <TuiCheckbox v-model="checkVal" appearance="button" direction="v">
        <TuiCheckboxItem v-for="i in 10" :key="i" :value="i">
          Check {{ i }}
        </TuiCheckboxItem>
      </TuiCheckbox>
    </TuiStepScroller>
  </div>
</template>

Control Buttons

Rich properties are provided to customize the position, size, and border style of the scrolling buttons.

• buttonPosition: Controls button placement; supports start (head), end (tail), both (both sides), and float (floating).
• buttonSize: Button size; supports small, default, and large.
• border: Border strategy:
• auto: Intelligent mode, typically used for button groups, showing only internal dividers.
• none: No-border mode, with gaps between elements.
• always: Force display of outer borders and dividers for a compact layout.

<script setup>
import { reactive } from 'vue'

const config = reactive({
  position: 'both',
  size: 'default',
  border: 'auto'
})
</script>

<template>
  <div class="control-panel">
    <TuiRadio v-model="config.position" :options="['start', 'end', 'both', 'float']" />
  </div>

  <div style="height: 60px;">
    <TuiStepScroller 
      :buttonPosition="config.position" 
      :buttonSize="config.size"
      :border="config.border"
    >
      <div v-for="i in 20" :key="i" class="item">{{ i }}</div>
    </TuiStepScroller>
  </div>
</template>

Scroll Mode

Use scrollMode to control the scrolling range when buttons are clicked.

• full: Full-page scrolling (default); clicks scroll one full screen of visible content.
• half: Half-page scrolling; clicks scroll half a screen of content, suitable for fine-tuning.

<template>
  <TuiStepScroller scrollMode="half" showPagination>
    </TuiStepScroller>
</template>

API Reference

Props

Property	Description	Type	Default
direction	Scroll direction, options: 'h' (horizontal), 'v' (vertical)	String	'h'
border	Border display strategy, options: 'auto', 'none', 'always'	String	'auto'
buttonPosition	Controls button position, options: 'both', 'start', 'end', 'float'	String	'both'
buttonSize	Controls button size, options: 'default', 'small', 'large'	String	'default'
scrollMode	Scroll distance mode, options: 'full', 'half'	String	'full'
showPagination	Whether to show pagination info (e.g., "1/5")	Boolean	true
wheelScroll	Whether to allow mouse wheel scrolling	Boolean	true
resizeObserver	Size monitoring strategy, options: 'self', 'global', 'none'	String	'self'

Expose

The component exposes the following methods and states, which can be called via ref.

Name	Description	Type
scrollTo	Scroll to specified position (index or pixels)	(index: number) => void
scrollSta	Scroll to start position	() => void
scrollEnd	Scroll to end position	() => void
initSize	Recalculate dimensions and layout	() => void
resetScrollInner	Reset internal scroll position	() => void
state	Internal state object (contains pageInfo, etc.)	Object

Slots

Slot Name	Description
default	Content within the scroll container