Dropdown Positioning

SelectContent handles its own positioning. When @floating-ui/vue is installed, the dropdown uses smart positioning that automatically flips and shifts to stay visible within the viewport. Without it, the dropdown falls back to CSS absolute positioning.

Default Positioning

By default, the dropdown opens below the input aligned to the start edge (bottom-start).

Default Positioning

<script setup lang="ts">
import { ref } from 'vue'
import {
  SelectRoot,
  SelectControl,
  SelectInput,
  SelectContent,
  SelectOption,
} from 'vue-superselect'

const selected = ref<string | null>(null)
const frameworks = ['Vue', 'React', 'Svelte', 'Solid', 'Angular', 'Lit', 'Ember', 'Qwik']
</script>

<template>
  <div class="pos-demo">
    <SelectRoot v-model="selected">
      <SelectControl class="pos-control">
        <SelectInput placeholder="Select a framework..." class="pos-input" />
      </SelectControl>
      <SelectContent placement="bottom-start" class="pos-content">
        <SelectOption
          v-for="fw in frameworks"
          :key="fw"
          v-slot="{ selected: isSelected, active }"
          :value="fw"
          :label="fw"
          class="pos-option"
          :class="{
            'pos-option--selected': isSelected,
            'pos-option--active': active,
          }"
        >
          {{ fw }}
        </SelectOption>
      </SelectContent>
    </SelectRoot>
    <p v-if="selected" class="pos-result">Selected: <strong>{{ selected }}</strong></p>
    <p class="demo-note">This styling is for demos only. The library ships zero CSS</p>
  </div>
</template>

<style scoped>
.pos-demo {
  max-width: 320px;
}

.pos-control {
  display: flex;
  align-items: center;
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 0.5rem 0.75rem;
  background: var(--vp-c-bg);
  transition: border-color 0.2s;
}

.pos-control:focus-within {
  border-color: var(--vp-c-brand-1);
  box-shadow: 0 0 0 2px var(--vp-c-brand-soft);
}

.pos-input {
  width: 100%;
  border: none;
  outline: none;
  font-size: 0.9375rem;
  background: transparent;
  color: var(--vp-c-text-1);
}

.pos-input::placeholder {
  color: var(--vp-c-text-3);
}

.pos-content {
  position: absolute;
  top: 100%;
  left: 0;
  right: 0;
  margin-top: 4px;
  background: var(--vp-c-bg);
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
  max-height: 240px;
  overflow-y: auto;
  z-index: 50;
  padding: 4px;
}

.pos-option {
  padding: 0.5rem 0.75rem;
  border-radius: 4px;
  cursor: pointer;
  font-size: 0.9375rem;
  color: var(--vp-c-text-1);
  transition: background-color 0.15s;
}

.pos-option--active {
  background-color: var(--vp-c-brand-soft);
}

.pos-option--selected {
  font-weight: 600;
  color: var(--vp-c-brand-1);
}

.pos-result {
  margin-top: 0.75rem;
  font-size: 0.875rem;
  color: var(--vp-c-text-2);
}
</style>

Placement Options

Control where the dropdown appears with the placement prop on SelectContent:

<SelectContent placement="bottom-start">
  <!-- ... -->
</SelectContent>

Available placements:

Placement	Description
bottom-start	Below, aligned to start (default)
bottom	Below, centered
bottom-end	Below, aligned to end
top-start	Above, aligned to start
top	Above, centered
top-end	Above, aligned to end

When @floating-ui/vue is installed, the dropdown automatically flips to the opposite side if there isn't enough room (e.g., bottom-start flips to top-start near the bottom of the viewport).

Floating UI vs CSS Fallback

vue-superselect treats @floating-ui/vue as an optional peer dependency:

• With @floating-ui/vue installed: Smart positioning with automatic flip and shift. The dropdown measures available space and repositions itself to stay visible.
• Without @floating-ui/vue: CSS fallback with position: absolute. The dropdown opens at the specified placement and does not reposition.

Install it if you need smart positioning:

npm

npm install @floating-ui/vue

yarn

yarn add @floating-ui/vue

pnpm

pnpm add @floating-ui/vue

No code changes are needed. SelectContent detects the package automatically and switches to smart positioning.

Collision Strategy

When using Floating UI, control how the dropdown handles collisions with the collision-strategy prop:

<SelectContent placement="bottom-start" collision-strategy="flip">
  <!-- ... -->
</SelectContent>

Strategy	Description
flip	Flip to the opposite side if not enough room (default)
none	Stay at the specified placement regardless of available space

Teleport for Overflow Containers

When a select is inside a container with overflow: hidden or overflow: auto, the dropdown gets clipped. Use the teleport prop to render the dropdown outside the container.

Teleport for Overflow Escape

<script setup lang="ts">
import { ref } from 'vue'
import {
  SelectRoot,
  SelectControl,
  SelectInput,
  SelectContent,
  SelectOption,
} from 'vue-superselect'

const selected = ref<string | null>(null)
const regions = ['North America', 'South America', 'Europe', 'Asia', 'Africa', 'Oceania']
</script>

<template>
  <div class="pt-demo">
    <p class="pt-hint">This select is inside an <code>overflow: hidden</code> container. The dropdown uses <code>teleport</code> to escape clipping.</p>
    <div class="pt-overflow-box">
      <p class="pt-box-label">overflow: hidden container</p>
      <SelectRoot v-model="selected">
        <SelectControl class="pt-control">
          <SelectInput placeholder="Select a region..." class="pt-input" />
        </SelectControl>
        <SelectContent
          :teleport="true"
          placement="bottom-start"
          class="pt-content"
        >
          <SelectOption
            v-for="region in regions"
            :key="region"
            v-slot="{ selected: isSelected, active }"
            :value="region"
            :label="region"
            class="pt-option"
            :class="{
              'pt-option--selected': isSelected,
              'pt-option--active': active,
            }"
          >
            {{ region }}
          </SelectOption>
        </SelectContent>
      </SelectRoot>
    </div>
    <p v-if="selected" class="pt-result">Selected: <strong>{{ selected }}</strong></p>
    <p class="demo-note">This styling is for demos only. The library ships zero CSS</p>
  </div>
</template>

<style scoped>
.pt-demo {
  max-width: 400px;
}

.pt-hint {
  margin-bottom: 0.75rem;
  font-size: 0.8125rem;
  color: var(--vp-c-text-3);
}

.pt-hint code {
  font-size: 0.8125rem;
  padding: 0.125rem 0.375rem;
  background-color: var(--vp-c-mute);
  border-radius: 3px;
}

.pt-overflow-box {
  border: 2px dashed var(--vp-c-divider);
  border-radius: 8px;
  padding: 1rem;
  height: 100px;
  overflow: hidden;
  position: relative;
}

.pt-box-label {
  margin: 0 0 0.5rem;
  font-size: 0.75rem;
  color: var(--vp-c-text-3);
  font-family: monospace;
}

.pt-control {
  display: flex;
  align-items: center;
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  padding: 0.5rem 0.75rem;
  background: var(--vp-c-bg);
  transition: border-color 0.2s;
}

.pt-control:focus-within {
  border-color: var(--vp-c-brand-1);
  box-shadow: 0 0 0 2px var(--vp-c-brand-soft);
}

.pt-input {
  width: 100%;
  border: none;
  outline: none;
  font-size: 0.9375rem;
  background: transparent;
  color: var(--vp-c-text-1);
}

.pt-input::placeholder {
  color: var(--vp-c-text-3);
}

.pt-result {
  margin-top: 0.75rem;
  font-size: 0.875rem;
  color: var(--vp-c-text-2);
}
</style>

<style>
/* Teleported content needs global styles since it escapes the component scope */
.pt-content {
  background: var(--vp-c-bg);
  border: 1px solid var(--vp-c-divider);
  border-radius: 8px;
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
  max-height: 200px;
  overflow-y: auto;
  z-index: 50;
  padding: 4px;
}

.pt-option {
  padding: 0.5rem 0.75rem;
  border-radius: 4px;
  cursor: pointer;
  font-size: 0.9375rem;
  color: var(--vp-c-text-1);
  transition: background-color 0.15s, color 0.15s, box-shadow 0.15s;
}

.pt-option:hover,
.pt-option--active {
  background-color: var(--vp-c-brand-soft);
}

.pt-option--selected {
  font-weight: 600;
  color: var(--vp-c-brand-1);
  box-shadow: inset 2px 0 0 var(--vp-c-brand-1);
}
</style>

Teleport Options

<!-- No teleport (default), dropdown is inline -->
<SelectContent :teleport="false">

<!-- Teleport to body -->
<SelectContent :teleport="true">

<!-- Teleport to a specific selector -->
<SelectContent teleport="#my-container">

Value	Behavior
false	Dropdown renders inline (default)
true	Dropdown teleports to <body>
"#selector"	Dropdown teleports to the specified element

When teleported to <body> with @floating-ui/vue installed, the dropdown remains visually positioned next to the input. It just lives in a different part of the DOM to escape overflow clipping.

Scoped styles and teleport

When using teleport, the dropdown content is rendered outside your component's DOM tree. Scoped styles (<style scoped>) will not apply to teleported content. Use global styles or CSS classes without the scoped attribute for the dropdown.

Force Absolute

The force-absolute prop disables Floating UI positioning and uses plain CSS position: absolute instead:

<SelectContent force-absolute>
  <!-- ... -->
</SelectContent>

This is useful when you want the dropdown to be positioned relative to a custom teleport target rather than the input.

Data Attributes for Styling

SelectContent exposes data attributes based on its current position:

/* Style based on which side the dropdown opened on */
[data-side="top"] {
  border-bottom: 2px solid var(--brand);
}

[data-side="bottom"] {
  border-top: 2px solid var(--brand);
}

Attribute	Values
data-side	"top", "bottom", "left", "right"
data-align	"start", "center", "end"

Summary

Scenario	Configuration
Simple dropdown	Default, no props needed
Specific placement	placement="top-start"
Inside scrollable container	:teleport="true"
Fixed placement (no flip)	collision-strategy="none"
Custom teleport target	teleport="#my-panel"
No Floating UI available	Works with CSS fallback automatically

Next Steps

• Basic Select
• Multi-Select
• Accessibility