Swipe Reveal

The m3e-swipe-reveal component reveals contextual actions behind content when swiped, and optionally dismisses the item.

import "@m3e/web/swipe-reveal";
Usage

This section outlines usage examples and configuration guidance for the components in this module.

Basic usage

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.

Item 1 Item 2 Item 3
<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;
}
Groups

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.

Triggers

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.

Item 1 Item 2
<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>
Thresholds and overshoot

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.

Stagger

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.

Item 1 Item 2 Item 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>
Dismissible

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.

Avoid overcrowding actions Dismiss is designed for a small number of actions. When actions consume most of the item's width, the actions must be fully revealed before dismissal becomes available. If the actions exceed the available item or viewport width, they are not automatically wrapped or made scrollable.
Item 1 Item 2 Item 3
Reset dismissed items
<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>
Elastic

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.

Card Header
Card Content
Card Footer
<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;
}
Accessibility

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.

Do not make swiping the only way to access an action. Provide an equivalent keyboard-operable way to reveal or invoke each action, and make sure controls are reachable in a logical focus order. Native module support

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.

API

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.

m3e-swipe-reveal m3e-swipe-reveal-group
On this page Swipe Reveal