State and Events

Components manage their own state unless you pass a controlled value. A change callback lets you respond in either case.

Set the Starting Value

Use a default prop to choose the starting state. Here, Bold starts pressed and changes when you click it:

<script setup lang="ts">
import { Toggle } from "@ui-sdk/vue/toggle"
</script>

<template>
  <Toggle default-pressed>Bold</Toggle>
</template>

The prop depends on the component: default-pressed, default-checked, default-open, or default-value.

Control the Value

Use v-model when the parent needs the current value:

<script setup lang="ts">
import { Toggle } from "@ui-sdk/vue/toggle"
import { ref } from "vue"

const pressed = ref(false)
</script>

<template>
  <Toggle v-model="pressed">Bold</Toggle>
  <output>{{ pressed ? "On" : "Off" }}</output>
</template>

v-model keeps the toggle’s pressed value in your ref. v-model:pressed works here too. Clicking Bold changes both the button and the output.

The main value depends on the component: checked for Checkbox, open for Popover, and value for Select. Name another binding when you need it, such as v-model:open on Select or v-model:query on Combobox.

If you pass :pressed without v-model, update that value yourself in @pressed-change. A value the parent never updates stays fixed.

To keep a value in the URL, update your ref through v-model or the event, then call router.push. A value that changes only when the navigation finishes leaves the component showing the old one until then, and logs a warning in development.

Respond to a Change

Events such as @pressed-change receive the requested value and details. They run before v-model updates.

For example, keep a popover open when someone clicks outside it:

<script setup lang="ts">
import {
  Popover,
  PopoverClose,
  PopoverContent,
  PopoverTitle,
  PopoverTrigger,
} from "@ui-sdk/vue/popover"

function keepOpen(
  open: boolean,
  details: { reason: string; cancel: () => void }
) {
  if (!open && details.reason === "outside-press") {
    details.cancel()
  }
}
</script>

<template>
  <Popover @open-change="keepOpen">
    <PopoverTrigger>Details</PopoverTrigger>
    <PopoverContent>
      <PopoverTitle>Project Details</PopoverTitle>
      <p>Last updated today.</p>
      <PopoverClose>Done</PopoverClose>
    </PopoverContent>
  </Popover>
</template>

The Done button still closes it. Cancellation also works when you control the value. Add debug to a root to log changes while you work.

Empty and Multiple Values

Select, Tabs, and Radio Group report null when nothing is selected. A multiple Select or Combobox uses an array. Accordion and Toggle Group always use arrays.

To change a component from outside its parts, use a Controller.