Components

Dropdown

GitHub

A Stimulus controller to create a dropdown.

Installation

  1. Install the package

    Terminal
    $ yarn add @stimulus-components/dropdown

  2. Register the controller in your application

    app/javascript/controllers/index.js
    import { Application } from '@hotwired/stimulus'
import Dropdown from '@stimulus-components/dropdown'

const application = Application.start()
application.register('dropdown', Dropdown)

This controller uses stimulus-use/use-transition under the hood. You can change the animation behavior as you want.

Example

Dropdown

Usage

app/views/index.html
<div data-controller="dropdown" class="relative">
  <button
    type="button"
    data-dropdown-target="button"
    data-action="dropdown#toggle click@window->dropdown#hide"
    aria-expanded="false"
    aria-controls="dropdown-menu"
  >
    Options
  </button>

  <div
    id="dropdown-menu"
    data-dropdown-target="menu"
    class="hidden transition transform origin-top-right absolute right-0"
    data-transition-enter-from="opacity-0 scale-95"
    data-transition-enter-to="opacity-100 scale-100"
    data-transition-leave-from="opacity-100 scale-100"
    data-transition-leave-to="opacity-0 scale-95"
  >
    <a href="#" data-action="dropdown#toggle">Account settings</a>
    <a href="#" data-action="dropdown#toggle">Support</a>
    <a href="#" data-action="dropdown#toggle">License</a>
  </div>
</div>

TailwindCSS is used in this example, but it's up to you to style the dropdown as you want.

Accessibility

The markup follows the ARIA disclosure pattern: the button that opens the menu points to it with aria-controls, and tells whether it is open with aria-expanded.

Add a button target to that button and the controller keeps aria-expanded in sync: it writes true when the menu opens and false when it closes, whether the menu is closed from the button, from an item, or by a click outside. The attribute is also corrected when the controller connects, so the initial value in your markup never drifts.

The target is optional. Without it the controller touches no attribute, and markup written before this behavior existed keeps working.

Extending Controller

You can use inheritance to extend the functionality of any Stimulus component:

app/javascript/controllers/dropdown_controller.js
import Dropdown from "@stimulus-components/dropdown"

export default class extends Dropdown {
  connect() {
    super.connect()
    console.log("Do what you want here.")
  }

  toggle(event) {
    super.toggle()
  }

  hide(event) {
    super.hide(event)
  }
}

This controller will automatically have access to targets defined in the parent class.

If you override the connect, disconnect or any other methods from the parent, you'll want to call super.method() to make sure the parent functionality is executed.