DOCSEARCHbyAlgolia
Submit Docs

Stimulus Tailwind Components

website·Indexed 31 days ago

https://stimulus-tailwind.chiefpansancolt.dev/

A collection of UI components for StimulusJS and Tailwind CSS, including a theme switcher for dark mode, modals, notifications, and toggle switches. Version 0.5.0.

Tokens
7.6K
Snippets
33
Records
39
Agent score
60%

What's inside Stimulus Tailwind Components

  1. Overview of StimulusJS Tailwind Components features

    The stimulus-tailwind-components package provides pre-built Stimulus controllers inspired by TailwindUI and HeadlessUI. Supported features include:

    • Notification: Notifications that can be manually or automatically dismissed within a specified zone.
    • Theme: Ability to toggle between Dark and Light themes, including system preference detection on load.
    • Switch: A toggle switch component.
    • Modal: Functionality to show and hide modal windows.

  2. Implement a Modal using the Stimulus-Tailwind Modal component

    The modal component provides a dialog box that can be opened and closed via buttons, keyboard shortcuts (ESC), or background clicks. It requires three specific targets: a container, a background overlay, and the modal view itself.
    <div
  data-controller="modal"
  data-modal-hide-class="hidden"
  data-modal-entering-class="ease-out duration-300"
  data-modal-leaving-class="ease-in duration-200"
  data-modal-to-background-class="opacity-100"
  data-modal-from-background-class="opacity-0"
  data-modal-to-view-class="opacity-100 translate-y-0 sm:scale-100"
  data-modal-from-view-class="opacity-0 translate-y-4 sm:translate-y-0 sm:scale-95"
>
  <!-- Trigger Button -->
  <button
    data-action="click->modal#open"
    type="button"
  >
    Open Modal
  </button>

  <!-- Modal Container -->
  <div
    data-modal-target="container"
    class="fixed inset-0 z-20 hidden overflow-y-auto"
  >
    <div class="flex items-center justify-center">
      <!-- Background Overlay -->
      <div
        data-modal-target="background"
        class="fixed inset-0 opacity-0 transition-opacity"
        data-action="click->modal#closeBackground"
        aria-hidden="true"
      >
        <div class="absolute inset-0 bg-gray-500 opacity-75"></div>
      </div>

      <!-- Modal View -->
      <div
        data-modal-target="view"
        class="inline-block transform rounded-lg bg-white p-6 shadow-xl transition-all"
        role="dialog"
        aria-modal="true"
      >
        <h3>Header Title</h3>
        <div>Modal content goes here.</div>
        <button data-action="click->modal#close">Close</button>
      </div>
    </div>
  </div>
</div>

  3. Add a new Stimulus controller

    When adding a new controller, place the file in the src folder. You must import the new controller in src/index.js to ensure it is included. After adding the controller and import, run the build command to compile the assets.
    pnpm build

  4. Report a bug in Stimulus Tailwind Components

    Before submitting a bug report, check the existing open bug issues to avoid duplicates. When reporting, use the official bug report template and provide as much detail as possible to help maintainers reproduce the behavior. If a previously closed issue is relevant to your current problem, open a new issue and include a link to the original closed issue.

  5. Use the Playground to test features

    The playground is used to create examples and verify feature changes. To add a feature to the playground:

    1. Create a new HTML file at playground/playground/<feature-name>/index.html.
    2. If adding a new controller, register it in docs/_layouts/default.html.
    3. Enable the feature in _data/features.yml.

    To run the playground, execute the following commands in separate terminal windows.

    cd playground
pnpm install
bundle install
pnpm tailwind:watch
pnpm docs:dev
pnpm docs:open

  6. Pre-commit checklist for contributors

    Before submitting a pull request, ensure the following requirements are met:

    • Documentation is added/updated and is findable on the documentation site.
    • Playground examples are created and added to the playground site.
    • Output is compiled in both the playground and dist folders.
    • The linter passes without errors using pnpm lint.
    pnpm lint

  7. Install stimulus-tailwind-components and dependencies

    To use stimulus-tailwind-components, you must first install @hotwired/stimulus and tailwindcss. While Tailwind CSS is the recommended styling library, it is not a hard dependency.
    # Install core dependencies
npm install @hotwired/stimulus@latest tailwindcss@latest
# OR
yarn add @hotwired/stimulus@latest tailwindcss@latest
# OR
pnpm add @hotwired/stimulus@latest tailwindcss@latest

# Install the components library
npm install stimulus-tailwind-components@latest
# OR
yarn add stimulus-tailwind-components@latest
# OR
pnpm add stimulus-tailwind-components@latest

  8. Manually dismiss a notification

    To allow users to manually close a notification, add a button or element with the data-action="notification#close" attribute inside the notification container.
    <button data-action="notification#close" type="button">
  <span class="sr-only">Close</span>
  <!-- Close Icon -->
</button>

  9. Set up the Stimulus-Tailwind development environment

    To contribute to the project, ensure you have the following versions installed: Ruby v3.1.2, Node v21+, and pnpm 8+. After cloning the repository, run the setup script from the project root to initialize the local environment.
    ./bin/setup

  10. Install dependencies for stimulus-tailwind-components

    Before installing stimulus-tailwind-components, you must add @hotwired/stimulus and tailwindcss to your project dependencies. While Tailwind CSS is the recommended styling library, it is not a hard dependency.
    # Using yarn
yarn add @hotwired/stimulus@latest tailwindcss@latest

# Using npm
npm install @hotwired/stimulus@latest tailwindcss@latest

# Using pnpm
pnpm add @hotwired/stimulus@latest tailwindcss@latest

  11. Submit a Pull Request to Stimulus Tailwind Components

    To ensure a pull request is considered by maintainers, follow these requirements:

    1. Use the provided Pull Request template.
    2. Verify that all status checks are passing after submission.
    3. If a status check fails and you believe it is unrelated to your changes, leave a comment on the PR explaining why; a maintainer will then re-run the check.

    Note that reviewers may request additional design work, tests, or changes before the PR is accepted.

  12. Implement manual dismissal for Notifications

    To allow users to manually close a notification, add a button with the notification#close action. This will trigger the leaving animation and remove the notification from the DOM.
    <button data-action="notification#close" type="button">
  <span class="sr-only">Close</span>
  <!-- SVG Icon -->
</button>