show

Updated on September 7, 2024Source codeTests

show is a function that can conditionally show or hide elements in the DOM, using the CSS display property under the hood. It works with static values—conditionally displaying once—and reactive values—showing and hiding elements each time the value changes.

Example

Example source code

The useTablist example is another good demo—it uses show under the hood to toggle an array of tab panel elements.

Usage

To conditionally display a DOM element, call the show function, which requires two parameters: the element or elements you're conditionally showing, and the condition the element or elements need to meet. show also accepts an optional options object as its final parameter.

import { show } from '@baleada/vue-features'

export function myCompositionFunction (...) {
  show(elementOrListOrPlane, condition[, options])
}

Here's a breakdown of the required parameters:

And here's a breakdown of the options object:

How to format your condition

There are several different ways to format the condition that show uses to determine whether or not an element should be displayed.

The simplest type of condition is a reactive reference to a Boolean:

import { ref } from 'vue'

const isShown = ref(true),
      myElement = ref(null) 
      // ☝️ A Vue component would populate this ref 
      // with a DOM element after the component is
      // mounted.

show(
  myElement,
  isShown,
)

show watches your reactive value for changes. When the value is true, your element is displayed, and when it's false, the element is hidden.

But what about when the element is a reactive array of elements, rather than a single reactive element reference? How do we make each element is correctly shown or hidden?

If you only need to conditionally display your elements once, you can pass the value getter instead of a reactive Boolean. The value getter is a callback function that receives only one argument: the index (Number) of a given element in your reactive array of elements. It should return true for elements that should be shown, and false for elements that should be hidden.

But more commonly, you'll need to conditionally display an array of elements based on some other piece of reactive data. For those cases, you can pass a reactive value getter as the key's value.

A reactive value getter is an object, as described in the bind guide. Here's a breakdown of that object:

Here's an example of how useTablist uses this feature to conditionally display tab panels, displaying only the currently selected panel:

export function useTablist (...) {
  ...

  show(
    // Reactive array of tab panel elements
    panels.list,
    {
      // `selected.value.newest` is a reactive reference to the
      // index of the currently selected tab panel.
      //
      // Every panel should be hidden, except for the panel
      // whose index is a match.
      //
      // This `get` callback should run again each time
      // `selected.value.newest` changes.
      get: index => index === selected.value.newest,
      watchSource: () => selected.value.newest,
    },
    options
  )

  ...
}

Finally, let's look at how this all works with a Plane, the Baleada Features data structure for an array of arrays of elements.

The value format for a Plane is almost identical to the format for arrays of elements. When you only need to conditionally display the elements in the Plane once, you can pass the value getter. The value getter for a Plane is a callback function that receives two arguments: the row index (Number) and column index (Number) of a given element in your Plane of elements. It should return true for elements that should be shown, and false for elements that should be hidden.

Here's an example of how that would look:

import { show } from '@baleada/vue-features'

export function myComposable (...) {
  ...

  show(
    // Reactive `Plane` of elements
    myPlane,
    {
      get: (row, column) => {
        // Based on `row` and `column`, return `true` for
        // elements that should be shown, and `false` for
        // elements that should be hidden.
      },
      watchSource: [
        // Any watch sources that should cause the `get` callback
        // to re-run and conditionally display each element again.
      ],
    },
    options
  )

  ...
}

How to format enter/leave transitions

As outlined above, show accepts an optional options object as its final parameter, and that object's only property is transition.

You can use this transition property to configure an enter/leave transition that will more smoothly show and hide your element or elements.

The API for show's transition option is inspired by the API of Vue's Transition component. Both CSS and JS transitions are supported.

The value of the transition property should be an object configuring your transition. That object can have these properties:

• appear
• enter
• leave

Each property of your transition config can either be a CSS transition or a JS transition, whose formats are explained in more detail in the next section.

Before diving in to transition formats, note a few points:

• It's possible to mix and match transitions, i.e. you can have a CSS enter transition and a JS leave transition.
• It's not required to define a transition for every state, i.e. you can define an enter transition with no leave transition.
• Just like with Vue's Transition component, you can set appear to true, and your element will use the enter transition when it first appears.

Now, let's go through the CSS and JS transition formats individually, and finish up by looking at type-safe transitions for TypeScript users.

CSS transitions

CSS transitions are configured by objects. Here's a breakdown of the CSS transition object:

Here's a more detailed breakdown of transition timing:

1. The optional start callback gets called
2. from classes get added
3. One animation frame later, active classes get added
4. One animation frame later, from classes get removed, and to classes get added
5. Transition eventually ends
6. One animation frame later, active and to classes get removed, and show calls the optional end callback

Cancel timing:

1. Transition is canceled by setting transition-property to none and removing from, active, and to classes
2. One animation frame later, transition-property is restored to its original value (if any) and show calls the optional cancel callback
3. show never calls the optional end callback

import { show } from '@baleada/vue-features'

show(
  myElement,
  myCondition,
  {
    transition: {
      // Example fade-in transition using Tailwind classes
      enter: {
        from: 'opacity-0 scale-[98%]',
        active: 'transition ease-out duration-150',
        to: 'opacity-100 scale-100',

        // Optional callbacks for post-transition side effects
        end: () => myElement.value.focus(),
        cancel: () => someOtherElement.value.focus(),
      }
    }
  }
)

JS transitions

JS transitions are configured by objects. Here's a breakdown of the JS transition object:

More info on the parameters passed to these callbacks:

• When you're transitioning a single element, the callbacks receive no parameters.
• When you're transitioning a list, the callbacks get called for each element, and the receive the index (number) of the element currently being transitioned.
• When you're transitioning a Plane, the callbacks get called for each element, and they receive the row (Number) and column (Number) of the element currently being transitioned.
• Remember that active receives its done parameter after any index/row/column parameters. Call done with no arguments when the JS transition has been completed.

import { show } from '@baleada/vue-features'

show(
  required,
  {
    transition: {
      enter: {
        before: ...,
        active: ...,
        after: ...,
        cancel: ...,
      },
      leave: {
        before: ...,
        active: ...,
        after: ...,
        cancel: ...,
      },
      appear: {
        before: ...,
        active: ...,
        after: ...,
        cancel: ...,
      },
    }
  }
)

Here's a more detailed breakdown of JS transition timing:

Type-safe transitions

Baleada Features exports a defineTransition helper function that you can use to define type-safe transition configurations for appear, enter, and leave.

defineTransition is a no-op—you pass in a transition configuration object as its first and only parameter, and the exact same object gets returned.

Type safety comes from the generic types that you can pass to defineTransition.

Here's a code example:

import { ref } from 'vue'
import {
  show,
  defineTransition,
  useElementApi
} from '@baleada/vue-features'

const element = ref<HTMLElement>()
const elementIsShown = ref(false)

show(
  element,
  elementIsShown,
  {
    transition: {
      appear: true,
      // It's recommended to use the `typeof` operator to infer
      // the first generic type, instead of manually passing a
      // valid type.
      //
      // The second generic type defines `enter` as a CSS transition.
      enter: defineTransition<typeof element, 'css'>({
        // `from`, `active`, and `to` are type-checked as strings
        from: ..., active: ..., to: ...,
        // `end` and `cancel` are type checked as functions
        end: ..., cancel: ...,
      }),

      // You can pass 'js' as the second generic to define a
      // type-safe JS transition:
      leave: defineTransition<typeof element, 'js'>({
        // All properties are type-checked as functions
        before: () => { ... },
        after: () => { ... },
        cancel: () => { ... },
        // The `active` function actually has a few different
        // signatures. For single elements, it just receives
        // the `done` callback as its first and only parameter.
        //
        // For lists and planes, though, it can receive the `index`
        // or the `row` & `column` as parameters, with the `done`
        // callback always passed as the last parameter. TypeScript
        // will correctly type-check all three of these variations
        // with the help of your generic types.
        active: (done) => { ... },
    }
  }
)

Edit doc on GitHub