Nefariously Programmed Mecha

    stimulus-reveal

    1.4.2 • Public • Published

    Stimulus Reveal

    Stimulus controller to hide/show elements with optional transitions

    Installation

    $ yarn add stimulus-reveal

    Usage

    Register the controller with Stimulus:

    // application.js
    import { Application } from 'stimulus';
    import RevealController from 'stimulus-reveal'
    
    const application = Application.start()
    application.register('reveal', RevealController)

    Initialize the controller on a container element, add an action to toggle elements, and add data-reveal attributes to elements you want to toggle:

    <div data-controller="reveal">
      <button type="button" data-action="reveal#toggle">Click me</button>
      <div hidden data-reveal>I toggle</div>
    </div>

    Deprecations

    • Using stimulus-reveal on <a> tags will no longer prevent the default event chain. If you are using <a> tags, consider changing to <button type="button">.

    Options

    Top Level options

    data-reveal-target-selector-value (default: [data-reveal])

    Setting this attribute to a selector will allow you to change the selector pattern for toggling elements.

    data-reveal-toggle-keys-value

    Setting this attribute to a comma separated list of lower-case key names will toggle the reveal when they're pressed.

    Example:

    <div data-reveal-toggle-keys-value="a">

    data-reveal-show-keys-value

    Setting this attribute to a comma separated list of lower-case key names will show the reveal when they're pressed.

    Example:

    <div data-reveal-toggle-keys-value="?">

    data-reveal-hide-keys-value

    Setting this attribute to a comma separated list of lower-case key names will close the reveal when they're pressed.

    Example:

    <div data-reveal-toggle-keys-value="escape">

    data-reveal-away-value

    Setting this attribute will close the reveal when the user clicks away from the reveal element.

    data-reveal-open-value (default: false)

    Setting this attribute to "true" will tell the controller that the default state is open for the reveal. The next toggle will close it.

    Trigger element options

    data-reveal-prevent-default

    If set on the trigger element, this will prevent the default action from being handled.

    data-reveal-stop-propagation

    If set on the trigger element, this will prevent the default action from being propagated.

    Element options

    You can set options per element to change how each one behaves.

    data-transition

    If set, this will enable transitions. A default transition will apply:

    In:

    • Opacity: 0 -> 1
    • Transform Scale: 95% -> 100%
    • Duration: 200ms

    Out:

    • Opacity: 1 -> 0
    • Transform Scale: 100% -> 95%
    • Duration: 150ms
    Example
    <div data-controller="reveal">
      <button type="button" data-action="reveal#toggle">Click me</button>
      <div hidden data-reveal data-transition>I toggle with transitions</div>
    </div>
    data-transition-(enter|leave), data-transition-(enter|leave)-start, data-transition-(enter|leave)-end

    These options can be used to override the default transitions by setting classes at transition points.

    Example
    <div data-controller="reveal">
      <button type="button" data-action="reveal#toggle">Click me</button>
      <div hidden data-reveal data-transition
        data-transition-enter="transition transform ease-out duration-200"
        data-transition-enter-start="opacity-0 -translate-y-6 bg-transparent"
        data-transition-enter-end="opacity-100 translate-y-0 bg-transparent"
        data-transition-leave="transition transform ease-out duration-150"
        data-transition-leave-start="opacity-100 translate-y-0 bg-transparent"
        data-transition-leave-end="opacity-0 -translate-y-6 bg-transparent">
        I toggle with custom transitions</div>
    </div>
    data-(enter|leave)-(start|end)

    These attributes allow you to toggle an element before or after the main transition. For instance if you need to unhide and element before an enter transition and hide it after a leave transition.

    Example
    <div data-controller="reveal">
      <button type="button" data-action="reveal#toggle">Click me</button>
      <div hidden data-reveal data-enter-start data-leave-end>
        <div hidden data-reveal data-transition
          data-transition-enter="transition transform ease-out duration-200"
          data-transition-enter-start="opacity-0 -translate-y-6 bg-transparent"
          data-transition-enter-end="opacity-100 translate-y-0 bg-transparent"
          data-transition-leave="transition transform ease-out duration-150"
          data-transition-leave-start="opacity-100 translate-y-0 bg-transparent"
          data-transition-leave-end="opacity-0 -translate-y-6 bg-transparent">
          I toggle with custom transitions</div>
      </div>
    </div>

    Methods

    show

    This will show toggled elements.

    Example
    <div data-controller="reveal">
      <button type="button" data-action="reveal#show">Click me</button>
      <div hidden data-reveal data-transition>I can't be hidden again</div>
    </div>

    hide

    This will hide toggled elements.

    Example
    <div data-controller="reveal">
      <button type="button" data-action="reveal#hide">Click me</button>
      <div data-reveal data-transition>I can't be shown again</div>
    </div>

    toggle

    This will toggle toggled elements.

    Example
    <div data-controller="reveal">
      <button type="button" data-action="reveal#toggle">Click me</button>
      <div hidden data-reveal data-transition>I will show and hide again and again and again</div>
    </div>

    stop

    This will stop the event from bubbling to parent elements.

    Example
    <div data-controller="reveal existence" data-action="reveal:hidden->existence#remove">
      <!-- reveal:hidden will bubble to here and remove the entire element from the DOM -->
      <button type="button" data-action="reveal#hide">Hide entire outer div</button>
      <div data-reveal>I get hidden along with the inner div when the first button is pressed</div>
      <div data-controller="reveal" data-action="reveal:hidden->reveal#stop">
        <!-- reveal:hidden will bubble to here then stop, preventing the existence#remove action above from happening -->
        <button type="button" data-action="reveal#hide">Hide inner div</button>
        <div data-reveal>I get hidden but the outer div does not hide if the second button is pressed</div>
        <div data-reveal>I also get hidden but the outer div does not hide if the second button is pressed</div>
      </div>
    </div>

    Events

    Stimulus Reveal emits a number of events during the lifecycle of a transition. They are listed below in the order in which they happen:

    Name Description
    reveal:show Emits before the show transition starts, on each target element
    reveal:hide Emits before the hide transition starts, on each target element
    reveal:shown Emits at the end of the show transition, on each target element
    reveal:hidden Emits at the end of the hide transition, on each target element
    reveal:complete Emits at the end of the transition, regardless of whether it is shown or hidden, on each target element

    Contributing

    Fork the project.

    Install dependencies

    $ yarn install

    Write some tests, and add your feature. Send a PR.

    Install

    npm i stimulus-reveal

    DownloadsWeekly Downloads

    1,482

    Version

    1.4.2

    License

    MIT

    Unpacked Size

    59.8 kB

    Total Files

    9

    Last publish

    Collaborators

    • simmerz