{% extends "component-demo-base.html" %} {% set TAG_NAME="x-deck" %} {% set COMPONENT_NAME="deck" %} {% block demoContent %}
<x-deck>
s are components that act similarly to slideshows or galleries where cards can be cycled independently of order with a variety of different transitions.
For basic transitions between <x-card>
s, simply call the .shufflePrev()
and .shuffleNext()
methods of the <x-deck>
.
Users can also call .shuffleTo(index)
if they already know the index of the target card in the deck.
// assume prevButton, nextButton, toButton, and deck
//are already defined as their respective DOM elements
prevButton.addEventListener("click", function(){
deck.shufflePrev();
});
nextButton.addEventListener("click", function(){
deck.shuffleNext();
});
toButton.addEventListener("click", function(){
deck.shuffleTo(1);
});
The .shufflePrev()
, .shuffleNext()
, and .shuffleTo()
methods can also be called with an optional direction parameter of either "forward"
or "reverse"
to specify how animations should progress.
If this parameter is "auto"
or not given, we automatically choose an animation direction depending on whether the new card is ahead of or behind the current card in the deck.
transition-type/.transitionType
The <x-deck>
's transition-type
attribute (also accessible by the .transitionType
property) controls how all cards in the deck animate in and out.
Valid options:
scrollLeft,
scrollUp,
scrollRight,
scrollDown,
flipX,
flipY,
coverLeft,
coverUp,
coverRight,
coverDown,
uncoverLeft,
uncoverUp,
uncoverRight,
uncoverDown,
none
// assume transitionButton and deck are already
// defined as their respective DOM elements
var types = [
"scrollLeft", "scrollUp", "scrollRight", "scrollDown",
"flipX", "flipY",
"coverLeft", "coverUp", "coverRight", "coverDown",
"uncoverLeft", "uncoverUp", "uncoverRight", "uncoverDown",
"none"
];
transitionButton.addEventListener("click", function(){
var oldType = deck.transitionType;
deck.transitionType = types[(types.indexOf(oldType)+1) % type.length];
// force animation to make visible for demo
deck.shuffleNext("forward");
});
transition-override/.transitionOverride
While the <x-deck>
's transition-type
attribute changes the animation of all cards, it is also possible to specify how a specific <x-card>
animates when entering the deck with the transition-override
attribute (also accessible through the .transitionOverride
property.
An <x-card>
's transition-override
attribute can take any of the same values as the <x-deck>
's transition-type
attribute.
To add or remove <x-card>
s from a deck, simply use .appendChild()
or .removeChild()
in the same way that any other DOM node would be added/removed.
// assume addButton, removeButton, and deck
//are already defined as their respective DOM elements
// also assume that .randomColor simply returns a random color rgb string
addButton.addEventListener("click", function(){
// deck.numCards retrieves the number of cards currently in the deck
var newIndex = deck.numCards;
var newCard = document.createElement("x-card");
newCard.style.backgroundColor = randomColor();
newCard.textContent = newIndex;
deck.appendChild(newCard);
// for demo, shuffle to newly inserted card
deck.shuffleTo(newIndex);
});
removeButton.addEventListener("click", function(){
if(deck.numCards > 0){
//deck.getCardAt retrieves the <x-card> at the given index
var lastCard = deck.getCardAt(deck.numCards-1);
deck.removeChild(lastCard);
}
});
Styling the <x-deck>
and <x-card>
elements can be done like any other DOM elements. (By default, the deck attempts to be 100% width and height of its parent element, but this can be overridden.)
However, the deck also provides some CSS selectors to customize how cards appear during animations.
To style how a card appears as it is transitioning out of the deck, apply styles to x-card[leaving]
To style how a card appears when it is specifically selected in the deck, apply styles to x-card[selected]
/* grey out leaving card */
#custom-styles x-card[leaving]{
text-shadow: none;
background-color: grey!important;
color: #ccc;
opacity: 0.6;
}
/* add caption to selected card */
#custom-styles x-card[selected]:after{
content: "selected";
display: block;
font-size: .2em;
}
shufflestart
, shuffleend
, cardadd
, and cardremove
When the deck is transitioning cards, it fires events in order to signal different stages of the animation.
The <x-deck>
fires a shufflestart
event when it has finished setting all attributes of the deck and is about to start a transition animation. This event also provides the following information in e.detail
:
{ 'oldCard': the previously selected x-card that the transition is animating away from, 'newCard': the x-card that the transition is animating towards }
The <x-deck>
fires a shuffleend
event when a transition animation has completed. Much like a transitionend
event, the shuffleend
event will not fire if interrupted by another transition, and will thus only fire on a full animation completion. This event also provides the following information in e.detail
:
{ 'oldCard': the previously selected x-card that the transition just animated away from, 'newCard': the x-card that the transition animated towards (ie: the now-selected card) }
In addition, when a deck's <x-card>
s are added or removed, the deck fires the cardadd
and cardremove
, respectively. Both of these events also provide the following information in e.detail
:
{ 'card': the x-card that was just added or removed }