The m3e-swipe-reveal component reveals contextual actions behind content when swiped, and
optionally dismisses the item.
import "@m3e/web/swipe-reveal";
This section outlines usage examples and configuration guidance for the components in this module.
Use m3e-swipe-reveal to reveal contextual actions through a swipe gesture. Place the content to
be swiped in the default slot and actions in the leading and trailing slots. Actions
in the leading slot are revealed by swiping toward the trailing edge, while actions in the
trailing slot are revealed by swiping toward the leading edge.
Revealed actions can be hidden by tapping or dragging the content. As actions are revealed and hidden,
revealing, revealed, and covered events are emitted. Actions can also
be revealed and hidden programmatically using the reveal() and close() methods.
Content and staggered items remain in their scrolling container and may be clipped by an ancestor's overflow. Add padding to the scrolling container to make room for displaced content or shadows.
The following example illustrates use of m3e-swipe-reveal with items in a segmented
m3e-list. See List for more information.
<m3e-list variant="segmented">
<m3e-swipe-reveal>
<m3e-icon-button slot="leading" aria-label="Pin" variant="tonal">
<m3e-icon name="keep" filled></m3e-icon>
</m3e-icon-button>
<m3e-list-item>Item 1</m3e-list-item>
<m3e-icon-button slot="trailing" aria-label="Bookmark" variant="tonal">
<m3e-icon name="bookmark" filled></m3e-icon>
</m3e-icon-button>
</m3e-swipe-reveal>
<!-- Additional items omitted for brevity -->
</m3e-list>
By default, m3e-list clips overflowing content. Use the following CSS to allow content to extend
beyond the list bounds.
m3e-list {
overflow: visible;
}
Swipe reveals coordinate with sibling swipe reveals by default. Opening one swipe reveal automatically covers other revealed sibling swipe reveals.
Use an m3e-swipe-reveal-group to define an explicit coordination scope and configure shared
behavior for multiple swipe reveals. Settings applied to the group are automatically propagated to nested
m3e-swipe-reveal instances, allowing common behavior to be configured once and applied
consistently throughout the group.
By default, actions are revealed by swiping. Use the triggers attribute to specify a
space-separated list of interactions: swipe, tap, double-tap, and
long-press. Non-swipe triggers reveal actions in the leading slot when present;
otherwise, they reveal actions in the trailing slot. Swipe gestures reveal actions on the side
indicated by the swipe direction.
The following illustrates triggering reveals for swipe and long-press. A
m3e-swipe-reveal-group is used to simply configuration.
<m3e-swipe-reveal-group triggers="swipe long-press">
<m3e-list variant="segmented">
<m3e-swipe-reveal>
<m3e-list-item>Item 1</m3e-list-item>
<m3e-icon-button slot="trailing" aria-label="Share" variant="tonal">
<m3e-icon name="share" filled></m3e-icon>
</m3e-icon-button>
</m3e-swipe-reveal>
<!-- Additional items omitted for brevity -->
</m3e-list>
</m3e-swipe-reveal-group>
Use the threshold attribute to control how far content must be dragged, as a fraction (
0 to 1) of the revealed actions' width, before the actions remain revealed when
released. The default value is 0.5. The same threshold is used in reverse when covering revealed
actions.
Use the overshoot attribute to control the maximum distance, in pixels, that content can be
dragged beyond fully revealing its actions. Actions expand with the overshoot. The default value is
8; set it to 0 to disable overshoot.
Use the stagger attribute (0 to 1) to make neighboring items follow a dragged item. The value is
a fraction of the dragged item's current offset, not a fixed distance, so the effect scales with the drag. A
value of 0 (default) disables staggering, and a small value such as 0.05 gives a
subtle effect.
Use the stagger-count attribute to control the maximum number of sibling items, on each side,
that participate in staggering. The default value is 3.
<m3e-swipe-reveal-group stagger="0.05">
<m3e-list variant="segmented">
<m3e-swipe-reveal>
<m3e-list-item>Item 1</m3e-list-item>
<m3e-icon-button slot="trailing" aria-label="Archive" variant="tonal">
<m3e-icon name="archive" filled></m3e-icon>
</m3e-icon-button>
</m3e-swipe-reveal>
<!-- Additional items omitted for brevity -->
</m3e-list>
</m3e-swipe-reveal-group>
Use the dismissible attribute to allow an item to be dismissed by continuing a swipe past its
actions. Valid values are leading, trailing, both and
none (default). The outermost action serves as the dismiss action. Listen for the
dismiss event, which is cancelable, and the dismissed event to respond. Call
restore() to bring a dismissed item back.
Use the dismiss-threshold attribute to control the fraction of an item's width, from
0 to 1, that must be dragged before the item is dismissed when released.
<m3e-swipe-reveal-group dismissible="trailing">
<m3e-list variant="segmented">
<m3e-swipe-reveal>
<m3e-list-item>Item 1</m3e-list-item>
<m3e-icon-button slot="trailing" aria-label="Delete" variant="tonal">
<m3e-icon name="delete" filled></m3e-icon>
</m3e-icon-button>
</m3e-swipe-reveal>
<!-- Additional items omitted for brevity -->
</m3e-list>
</m3e-swipe-reveal-group>
By default, actions on both sides are elastic: they compress as they are revealed and expand as additional
space becomes available. If content is dragged beyond fully revealing its actions, both the actions and their
container continue expanding to occupy the overshoot. Set elastic to leading,
trailing, both (default), or none to control which sides behave this
way.
The card example below disables elasticity with elastic="none". This allows the revealed action
to behave like a fixed panel behind the card rather than stretching and resizing during interaction.
<m3e-swipe-reveal class="card-reveal" elastic="none">
<m3e-icon-button slot="leading" aria-label="Favorite" toggle variant="filled">
<m3e-icon name="favorite"></m3e-icon>
</m3e-icon-button>
<m3e-card>…</m3e-card>
</m3e-swipe-reveal>
.card-reveal {
--m3e-swipe-reveal-actions-padding: 0px;
--m3e-swipe-reveal-actions-underlap: var(--md-sys-shape-corner-value-medium);
--m3e-icon-button-container-height: 100%;
--m3e-icon-button-start-start-shape: var(--md-sys-shape-corner-value-medium);
--m3e-icon-button-end-start-shape: var(--md-sys-shape-corner-value-medium);
--m3e-icon-button-start-end-shape: 0px;
--m3e-icon-button-end-end-shape: 0px;
}
.card-reveal m3e-icon-button[slot="leading"] {
width: 64px;
}
.card-reveal m3e-icon-button[slot="leading"] m3e-icon {
position: absolute;
top: 16px;
margin-inline-start: -8px;
}
The m3e-swipe-reveal and m3e-swipe-reveal-group elements have the ARIA role
none, so they are purely presentational and add no semantics of their own. This allows them to
wrap items of a list, such as m3e-list-item, without breaking the relationship between the list
and its items in the accessibility tree.
The @m3e/web package uses
JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.
<script type="module" src="/node_modules/@m3e/web/dist/swipe-reveal.js"></script>
In addition, you must use an import map to include dependencies.
<script type="importmap">
{
"imports": {
"tslib": "https://cdn.jsdelivr.net/npm/tslib@2.8.1/+esm",
"lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
"lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.0/",
"lit-html": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/+esm",
"lit-html/directive.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directive.js",
"lit-html/directives/if-defined.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/if-defined.js",
"lit-html/directives/class-map.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/class-map.js",
"@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/+esm",
"@lit/reactive-element/": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/",
"@m3e/web/core": "/node_modules/@m3e/web/dist/core.js",
"@m3e/web/core/bidi": "/node_modules/@m3e/web/dist/core-bidi.js",
"@m3e/web/gestures": "/node_modules/@m3e/web/dist/gestures.js",
"@m3e/web/gestures/swipe": "/node_modules/@m3e/web/dist/gestures-swipe.js",
"@m3e/web/gestures/tap": "/node_modules/@m3e/web/dist/gestures-tap.js",
"@m3e/web/gestures/repeat": "/node_modules/@m3e/web/dist/gestures-repeat.js",
"@m3e/web/gestures/long-press": "/node_modules/@m3e/web/dist/gestures-long-press.js"
}
}
</script>
For production builds, use the minified files to ensure optimal load performance.
The @m3e/web package includes a
Custom Elements Manifest
(custom-elements.json), which documents the properties, attributes, slots, events and CSS custom
properties of each component.
You can explore the API below, or integrate the manifest into your own tooling.