index.md

Popover

Popovers are visually hiden menus of items activated by a simple button. Use popovers to create complex menus in a visually appealing way.

Prop	Data type	Required?	Description
items	Array<Item>	Yes	A list of menu items.
v-model:open	Boolean	Yes	Controls whether the popover is open or not.
click-outside	Boolean	No	Controls whether clicking outside the popover closes it.

Items

Popovers contain a list of menu items. Items can contain different information based on their type.

Button

A button is a clickable item users can interact with. It can take the form of a link or an action.

Property	Data type	Required?	Description
type	String	Yes	The item type (button).
text	String	Yes	The text that appears in the menu.
icon	String	Yes	The icon that appears in the menu.
click	Event	Yes	The action that triggers when a user clicks the button.

<script-setup lang="ts">
const items = [
  {    
    type: 'button',
    text: 'Report',
    icon: 'bi-exclamation',
    click: () => {}
  }
]

const open = ref(false)
</script>

<template>
  <fw-options-button @click="open = !open" />
  <fw-popover :items="items" v-model:open="open" />
</template

<fw-options-button @click="singleButton = !singleButton" />

Select

A select is a checkbox item that users can select or deselect to modify data.

Property	Data type	Required?	Description
type	String	Yes	The item type (select).
text	String	Yes	The text that appears in the menu.
model	Property	Yes	The property the select button maps to.

<script-setup lang="ts">
const items = [
  {
    type: 'select',
    text: 'Bandcamp',
    model: bandcamp
  }
]

const open = ref(false)
</script>

<template>
  <fw-options-button @click="open = !open" />
  <fw-popover :items="items" v-model:open="open" />
</template>

<fw-options-button @click="singleSelect = !singleSelect" />

Separator

Property	Data type	Required?	Description
type	String	Yes	The item type (separator).

Separators are visual separators that break the menu up into different sections.

<script-setup lang="ts">
const items=[
  {
    type: 'separator'
  }
]
</script>

<template>
  <fw-options-button @click="open = !open" />
  <fw-popover :items="items" v-model:open="open" />
</template>

<fw-options-button @click="separator = !separator" />

Nested items

To create a more complex menu, you can nest items within other menu items. Add a new items array inside an item to nest the array as an expanded list.

<script-setup lang="ts">
const items = [
  {
    type: 'button',
    text: 'Organize and share',
    icon: 'bi-collection',
    click: () => {},
    items: [
      {
        type: 'select',
        text: 'Bandcamp',
        model: bandcamp,
      }
    ]
  }
]

const open = ref(false)
</script>

<template>
  <fw-options-button @click="open = !open" />
  <fw-popover :items="items" v-model:open="open" />
</template

<fw-options-button @click="singleButton = !singleButton" />

Extra items

::: info Extra items can only be added to button and select items. :::

You can extend items without creating submenus by attaching a small extra menu on the right hand side of the item.

Property	Data type	Required?	Description
type	String	Yes	The item type.

::: details Supported types

• circle-button – a small clickable circle button
• library-privacy-level – a selectable list of Funkwhale privacy levels

:::

<script-setup lang="ts">
const items = [
  {
    type: 'select',
    text: 'Bandcamp',
    model: bandcamp,
    extraItems: [
      {
        type: 'library-privacy-level',
        model: bandcampPrivacy
      }
    ]
  },
  {
    type: 'select',
    text: 'Creative Commons',
    model: cc,
    extraItems: [
      {
        type: 'circle-button',
        icon: 'bi-exclamation',
        click: () => {}
      }
    ]
  }
]

const open = ref(false)
</script>
<template>
  <fw-options-button @click="open = !open" />
  <fw-popover :items="items" v-model:open="open" />
</template>

<fw-options-button @click="extraItemsOpen = !extraItemsOpen" />

Menu

Here is an example of a completed menu containing all supported features.

<fw-options-button @click="open = !open" />
<fw-popover :items="items" v-model:open="open" />

<fw-options-button @click="open = !open" />