Cuttlefish Docs
  • English

    • spz-selector

    When to use

    • When you need to scroll the currently selected content into the visible area after selection.
    • When you need to save the selection record, and it does not return to the initial value after refreshing the page.

    Code demonstration

    Basic usage

    The most basic usage, defaulting to select the first option.

    <spz-selector layout="container">
  <div option="A" selected>A</div>
  <div option="B">B</div>
  <div option="C">C</div>
</spz-selector>

    Maintain selected status

    Maintain the status of the last selection after refreshing the page.

    <spz-selector layout="container" record-state>
  <div option="A" name="A">A</div>
  <div option="B" name="B" selected>B</div>
  <div option="C" name="C">C</div>
</spz-selector>

    Mouse hover on option

    Display the value of the option hovered over by the mouse.

    <spz-selector layout="container" multiple @mouseover="mouseover-render.rerender(data=event);">
  <div option="A" name="A" selected>A</div>
  <div option="B" name="B">B</div>
  <div option="C" name="C">C</div>
  <div option="D" name="D">D</div>
  <div option="E" name="E">E</div>
</spz-selector>

<spz-render layout="container" manual id="mouseover-render">
  <ul>
    <li>Selected Option: <span>["A"]</span></li>
    <li>Mouseover Option: <span>A</span></li>
  </ul>
  <template>
    <ul>
      <li>Selected Option: <span>${JSON.stringify(selectedOptions)}</span></li>
      <li>Mouseover Option: <span>${targetOption}</span></li>
    </ul>
  </template>
</spz-render>

    Scroll into the viewport visible range

    Select the button, switch the option being selected, scroll to the visible range of the viewport when the current option is not in the viewport.

    <spz-selector layout="container" id="scroll-view">
  <div scroll-container>
    <div option="A" name="A" selected>A</div>
    <div option="B" name="B">B</div>
    <div option="C" name="C">C</div>
    <div option="D" name="D">D</div>
    <div option="E" name="E">E</div>
  </div>
</spz-selector>

<div class="buttons">
  <button @tap="scroll-view.toggle(option='A', value=true, isScrollIntoView=true)">A</button>
  <button @tap="scroll-view.toggle(option='C', value=true, isScrollIntoView=true)">C</button>
  <button @tap="scroll-view.toggle(option='D', value=true, isScrollIntoView=true)">D</button>
</div>

    Properties

    Property NameDescriptionTypeDefault ValueRequired
    multipleIf this property exists, supports multiple selection--No
    record-stateIf this property exists, supports saving the record of currently selected options, and the selection remains the same after refreshing the current page--No
    scroll-containerIf this property is configured in a child element of the element, it enables scrolling the selected option into the visible range of the viewport--No

    Option properties

    Property NameDescriptionTypeDefault ValueRequired
    optionValuestring | Object-Yes
    nameValue used for saving recordsstring-No, unless record-state is configured
    selectedIf this property exists, it indicates the current option is selected by defaultstring-No

    Methods

    toggle

    Parameter NameDescriptionTypeRequired
    optionOption valuestringYes
    valueWhether to select the specified optionbooleanYes
    isScrollIntoViewWhether to scroll the current option into the visible range, only effective when the function of scrolling into the visible range is enabledbooleanNo

    Events

    event object data

    PropertyDescriptionType
    eventNameName of the currently triggered eventstring
    targetOptionValue of the currently operated optionstring
    targetOptionAsJsonValue of the currently operated option (parsed as JSON)null | Object
    selectedOptionsValues of the currently selected optionsArray

    select

    • In single selection mode, this event is automatically triggered when an option changes from unselected to selected.
    • In multiple selection mode, this event is automatically triggered when the selected status of an option changes.

    mouseover

    This event is automatically triggered when the mouse hovers over an option.

    mouseout

    This event is automatically triggered when the mouse moves out of an option.

    AI Summary (LLM Ready)

    • Component ID: spz-selector
    • One-line purpose: Select from a group of lists.
    • Detected attribute rows: 0
    • Detected method subsections: 1
    • Detected event subsections: 4
    • Top attribute names: none (needs manual completion)
    • Top method names: toggle
    • Top event names: select, mouseover, mouseout
    • Reading order: start from usage/examples, then verify attributes, methods, and events.
    • Related docs: /en/guide/actions-and-events/ , /en/guide/layouts/