Files
basecoat/docs/src/components/dropdown-menu.njk
T

366 lines
12 KiB
Plaintext
Raw Normal View History

2025-04-25 16:42:10 +08:00
---
2025-05-01 12:50:40 +08:00
layout: layouts/page.njk
2025-04-25 16:42:10 +08:00
title: Dropdown Menu
description: Displays a menu to the user — such as a set of actions or functions — triggered by a button.
2025-04-29 19:14:31 +08:00
toc:
- label: Usage
id: usage
children:
- label: HTML + Javascript
id: usage-default
2025-05-07 12:03:38 +08:00
- label: Jinja and Nunjucks
id: usage-macro
2025-04-29 19:14:31 +08:00
- label: Examples
id: examples
children:
- label: Checkboxes
id: example-checkboxes
- label: Radio Group
id: example-radio-group
2025-04-25 16:42:10 +08:00
---
{% from "macros/code_block.njk" import code_block %}
2025-04-25 23:14:05 +08:00
{% from "macros/code_preview.njk" import code_preview %}
2025-05-01 20:53:03 +08:00
{% from "dropdown-menu.njk" import dropdown_menu %}
2025-04-25 23:14:05 +08:00
2025-04-29 19:14:31 +08:00
{% set code_html %}
{% call dropdown_menu(
2025-04-25 16:42:10 +08:00
id="dropdown-menu",
2025-04-25 23:14:05 +08:00
trigger="Open",
2025-04-25 16:42:10 +08:00
trigger_attrs={"class": "btn-outline"},
2025-04-26 11:59:53 +08:00
content_attrs={"class": "min-w-56"},
register_on=["alpine:init", "htmx:afterSwap"]
2025-04-25 16:42:10 +08:00
) %}
2025-04-29 19:14:31 +08:00
<div role="group" aria-labelledby="account-options">
<span id="account-options" role="heading">My Account</span>
<button type="button" role="menuitem">
Profile
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⇧⌘P</span>
</button>
<button type="button" role="menuitem">
Billing
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘B</span>
</button>
<button type="button" role="menuitem">
Settings
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘S</span>
</button>
<button type="button" role="menuitem">
Keyboard shortcuts
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘K</span>
</button>
</div>
<hr role="separator">
<button type="button" role="menuitem">
GitHub
</button>
<button type="button" role="menuitem">
Support
</button>
<button type="button" role="menuitem" disabled>
API
</button>
<hr role="separator">
<button type="button" role="menuitem">
Logout
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⇧⌘P</span>
</button>
{% endcall %}
{% endset %}
{% set code_script %}
2025-05-01 20:53:03 +08:00
<script>
{% fetchCode "src/js/dropdown-menu.js" %}
document.addEventListener('alpine:init', () => {
window.basecoat.registerDropdownMenu(Alpine);
});
</script>
2025-04-29 19:14:31 +08:00
{% endset %}
{{ code_preview("dropdown-menu", code_script | prettyHtml ~ code_html | prettyHtml) }}
<h2 id="usage">Usage</h2>
<h3 id="usage-default"><a href="#usage-default">HTML + Javascript</a></h3>
<div class="alert my-6">
{% lucide "circle-alert" %}
<h2>This component requires Javascript.</h2>
</div>
2025-05-01 20:53:03 +08:00
<section class="prose">
2025-04-29 19:14:31 +08:00
<p>The component is structured as such:</p>
<ul>
<li>A <code>&lt;div class="popover"&gt;</code> which wraps around the entire component and holds it state (e.g. open/close).</li>
<li>A <code>&lt;button&gt;</code> that acts as the trigger to open or close the popover.</li>
<li>A <code>&lt;div data-popover&gt;</code> that holds the content of the popover.</li>
<li>Inside of the <code>&lt;div data-popover&gt;</code> is a <code>&lt;nav role="menu"&gt;</code> that contains a combination of:
<ul>
<li><code>&lt;button role="menuitem"&gt;</code> for menu items.</li>
<li><code>&lt;button role="menuitemcheckbox"&gt;</code> for menu items with checkboxes.</li>
<li><code>&lt;button role="menuitemradio"&gt;</code> for menu items with radio buttons.</li>
<li><code>&lt;hr role="separator"&gt;</code> to display a horizontal separator.</li>
<li><code>&lt;div role="group"&gt;</code> to group options.</li>
<li><code>&lt;span role="heading"&gt;</code> for group headings.</li>
</ul>
</ul>
<p>As with the <a href="/components/popover">Popover</a> component, you can set up a few additional options on the <code>&lt;div data-popover&gt;</code> element:</p>
<ul>
<li><code>data-side</code> can be set to <code>top</code>, <code>bottom</code>, <code>left</code>, or <code>right</code> to change the side of the popover.</li>
<li><code>data-align</code> can be set to <code>start</code>, <code>center</code>, or <code>end</code> to change the alignment of the popover.</li>
</ul>
2025-05-07 12:03:38 +08:00
<p>You can include the Javascript code provided below, load it as an individual file or use the CLI. Some Alpine.js properties are also required on certain elements (e.g. <code class="text-xs">x-bind</code>, <code class="text-xs">x-data</code>, <code class="text-xs">@click</code>).</p>
2025-04-29 19:14:31 +08:00
</section>
2025-05-07 14:57:30 +08:00
<div class="flex gap-2 my-6">
<a class="badge-outline" href="/installation/#install-js">
Components with Javascript
{% lucide "arrow-right" %}
</a>
<a class="badge-outline" href="/installation/#install-cli">
Use the CLI
{% lucide "arrow-right" %}
</a>
<a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/js/dropdown-menu.js" target="_blank">
Individual JS file (dropdown-menu.js)
{% lucide "arrow-right" %}
</a>
</div>
2025-05-01 20:53:03 +08:00
{% from "tabs.njk" import tabs %}
2025-04-29 19:14:31 +08:00
{% set tabsets = [
2025-05-01 20:53:03 +08:00
{ tab: "HTML", panel: code_block(code_html | prettyHtml, class="") },
{ tab: "Javascipt (Alpine.js)", panel: code_block(code_script | prettyHtml, class="") }
2025-04-29 19:14:31 +08:00
] %}
{{ tabs(id="dropdown-menu", tabsets=tabsets) }}
2025-05-07 12:03:38 +08:00
<h3 id="usage-macro"><a href="#usage-macro">Jinja and Nunjucks</a></h3>
2025-04-29 19:14:31 +08:00
2025-05-07 12:03:38 +08:00
<div class="prose">
<p>You can use the <code class="relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-xs">dropdown_menu()</code> Nunjucks or Jinja macro for this component.</p>
</div>
<div class="flex gap-2 my-6">
<a class="badge-outline" href="/installation/#install-macros" target="_blank">
Use Nunjucks or Jinja macros
{% lucide "arrow-right" %}
</a>
<a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/jinja/dropdown-menu.html.jinja" target="_blank">
Jinja macro
{% lucide "arrow-right" %}
</a>
<a class="badge-outline" href="https://github.com/hunvreus/basecoat/blob/main/src/nunjucks/dropdown-menu.njk" target="_blank">
Nunjucks macro
{% lucide "arrow-right" %}
</a>
</div>
2025-04-29 19:14:31 +08:00
{% set raw_code %}{% raw %}{% call dropdown_menu(
id="dropdown-menu",
trigger="Open",
trigger_attrs={"class": "btn-outline"},
content_attrs={"class": "min-w-56"},
register_on=["alpine:init", "htmx:afterSwap"]
) %}
<div role="group" aria-labelledby="account-options">
<span id="account-options" role="heading">My Account</span>
<button type="button" role="menuitem">
Profile
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⇧⌘P</span>
</button>
<button type="button" role="menuitem">
Billing
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘B</span>
</button>
<button type="button" role="menuitem">
Settings
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘S</span>
</button>
<button type="button" role="menuitem">
Keyboard shortcuts
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘K</span>
</button>
</div>
<hr role="separator">
<button type="button" role="menuitem">
GitHub
</button>
<button type="button" role="menuitem">
Support
</button>
<button type="button" role="menuitem" disabled>
API
</button>
<hr role="separator">
<button type="button" role="menuitem">
Logout
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⇧⌘P</span>
</button>
{% endcall %}{% endraw %}{% endset%}
{{ code_block(raw_code, "jinja") }}
<h2 id="examples"><a href="#examples">Examples</a></h2>
<h3 id="example-checkboxes"><a href="#example-checkboxes">Checkboxes</a></h3>
{% set code %}{% call dropdown_menu(
id="dropdown-menu-checkboxes",
trigger="Open",
trigger_attrs={"class": "btn-outline"},
content_attrs={"class": "min-w-56"},
register_on=["alpine:init", "htmx:afterSwap"]
) %}
2025-04-25 16:42:10 +08:00
<div role="group" aria-labelledby="account-options">
<span id="account-options" role="heading">Account Options</span>
<button type="button" role="menuitem">
2025-04-25 23:14:05 +08:00
{% lucide "user" %}
2025-04-25 16:42:10 +08:00
Profile
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⇧⌘P</span>
</button>
<button type="button" role="menuitem">
2025-04-25 23:14:05 +08:00
{% lucide "credit-card" %}
2025-04-25 16:42:10 +08:00
Billing
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘B</span>
</button>
<button type="button" role="menuitem">
2025-04-25 23:14:05 +08:00
{% lucide "settings" %}
2025-04-25 16:42:10 +08:00
Settings
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘S</span>
</button>
</div>
<hr role="separator">
2025-04-29 19:14:31 +08:00
<div role="group" aria-labelledby="appearance-options">
<span id="appearance-options" role="heading">Appearance</span>
<button
type="button"
role="menuitemcheckbox"
aria-checked="true"
class="group"
x-data="{ checked: true }"
@click="checked = !checked"
:aria-checked="checked"
>
{% lucide "check", {
"class": "invisible group-aria-checked:visible",
"aria-hidden": "true",
"focusable": "false"
} %}
Status Bar
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⇧⌘P</span>
</button>
<button
type="button"
role="menuitemcheckbox"
aria-checked="false"
class="group"
disabled
x-data="{ checked: false }"
@click="checked = !checked"
:aria-checked="checked"
>
{% lucide "check", {
"class": "invisible group-aria-checked:visible",
"aria-hidden": "true",
"focusable": "false"
} %}
Activity Bar
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘B</span>
</button>
<button
type="button"
role="menuitemcheckbox"
aria-checked="false"
class="group"
x-data="{ checked: false }"
@click="checked = !checked"
:aria-checked="checked"
>
{% lucide "check", {
"class": "invisible group-aria-checked:visible",
"aria-hidden": "true",
"focusable": "false"
} %}
Panel
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘S</span>
</button>
</div>
2025-04-25 16:42:10 +08:00
<hr role="separator">
<button type="button" role="menuitem">
2025-04-25 23:14:05 +08:00
{% lucide "log-out" %}
2025-04-25 16:42:10 +08:00
Logout
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⇧⌘P</span>
2025-04-29 19:14:31 +08:00
</button>
{% endcall %}{% endset %}
{{ code_preview("dropdown-menu-checkboxes", code | prettyHtml) }}
2025-04-25 16:42:10 +08:00
2025-04-29 19:14:31 +08:00
<h3 id="example-radio-group"><a href="#example-radio-group">Radio Group</a></h3>
2025-04-25 16:42:10 +08:00
2025-04-29 19:14:31 +08:00
{% set code %}{% call dropdown_menu(
id="dropdown-menu-radio-group",
trigger="Open",
trigger_attrs={"class": "btn-outline"},
content_attrs={"class": "min-w-56"},
register_on=["alpine:init", "htmx:afterSwap"]
) %}
<div role="group" aria-labelledby="position-options" x-data="{ checked: 'bottom' }">
<span id="position-options" role="heading">Panel Position</span>
<hr role="separator">
<button
type="button"
role="menuitemradio"
aria-checked="false"
class="group"
@click="checked = 'top'"
:aria-checked="checked == 'top'"
>
<div class="size-4 flex items-center justify-center">
<div
class="size-2 rounded-full bg-foreground invisible group-aria-checked:visible"
aria-hidden="true",
focusable="false"
></div>
</div>
Status Bar
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⇧⌘P</span>
</button>
<button
type="button"
role="menuitemradio"
aria-checked="false"
class="group"
@click="checked = 'bottom'"
:aria-checked="checked == 'bottom'"
>
<div class="size-4 flex items-center justify-center">
<div
class="size-2 rounded-full bg-foreground invisible group-aria-checked:visible"
aria-hidden="true",
focusable="false"
></div>
</div>
Activity Bar
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘B</span>
</button>
<button
type="button"
role="menuitemradio"
aria-checked="false"
class="group"
@click="checked = 'right'"
:aria-checked="checked == 'right'"
>
<div class="size-4 flex items-center justify-center">
<div
class="size-2 rounded-full bg-foreground invisible group-aria-checked:visible"
aria-hidden="true",
focusable="false"
></div>
</div>
Panel
<span class="text-muted-foreground ml-auto text-xs tracking-widest">⌘S</span>
</button>
</div>
{% endcall %}{% endset %}
{{ code_preview("dropdown-menu", code | prettyHtml) }}