GUILD OF GLEKS UIv21.19.0

gogRipple

Ripple

A pointer-position wash that grows from where you pressed and fades when you let go. A directive, not a component, so it goes on any element you already have — no wrapper, no layout change. Built from scratch: there is no CDK in this library.

Overview

Import the directive and put it on the element you want pressed. Press and hold: the wave grows and stays until you let go. The demos on this page are the directive on markup of their own, which is always explicit — the library's own components are off until switched on.

typescript
import { GogRippleDirective } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [GogRippleDirective],
})

Basic usage — four surfaces of your own, each clipping the wash to its own corners:

A pill
Square corners
A larger tile, so the wave has room to travel
<!-- Ordinary markup of your own: the directive adds no wrapper and changes no layout. -->
<button
  type="button"
  gogRipple
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
    border-radius: var(--gog-radius);
  "
>
  Plain button
</button>
<div
  gogRipple
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
    border-radius: 999px;
  "
>
  A pill
</div>
<div
  gogRipple
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
  "
>
  Square corners
</div>
<div
  gogRipple
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
    border-radius: var(--gog-radius);
    min-height: 96px;
  "
>
  A larger tile, so the wave has room to travel
</div>

Examples

Settings and shapes

Press any surface — the matrix is live. Keyboard activation is always centred, since Enter and Space carry no coordinates; rippleCentred makes the pointer behave the same way. rippleDisabled detaches the listeners and drops the host class rather than ignoring events, so a switched-off ripple costs nothing. A host carrying disabled or aria-disabled="true" does not answer a press it will not act on. Under prefers-reduced-motion: reduce nothing ripples at all — suppressed outright rather than shortened.

gogRipple
rippleCentred
rippleDisabled
disabled
aria-disabled
@for (setting of settings; track setting.name) {
  <div>
    <span>{{ setting.name }}</span>
    @for (radius of radii; track radius) {
      <button
        type="button"
        gogRipple
        [rippleCentred]="setting.centred"
        [rippleDisabled]="setting.rippleDisabled"
        [disabled]="setting.disabled"
        [attr.aria-disabled]="setting.ariaDisabled ? 'true' : null"
        style="
          padding: 12px 20px;
          border: 1px solid var(--gog-border-color);
          background: var(--gog-surface-color);
          color: inherit;
          font: inherit;
        "
        [style.border-radius]="radius"
        [style.opacity]="setting.disabled || setting.ariaDisabled ? 0.55 : null"
      >
        Press
      </button>
    }
  </div>
}

Put it on the element that paints the surface

The one sharp edge in this API. The wash lives in its own layer, and that layer takes its corner radius from its host with border-radius: inherit — exact, per instance, per theme, with no token to declare. The cost is that on a wrapper whose child paints the rounded background, the layer inherits the wrapper's radius — very often 0 — and the wash squares off at the corners.

Both buttons below are ripple-wrapped; only the second has the directive on the element that actually has the radius. Press each and watch the corners.

<!-- Wrong: the wrapper has no radius, so the layer inherits 0 and the wash squares off. -->
<span gogRipple style="display: inline-block">
  <button
    type="button"
    style="
      padding: 12px 20px;
      border: 1px solid var(--gog-border-color);
      background: var(--gog-surface-color);
      color: inherit;
      font: inherit;
      border-radius: 999px;
    "
  >
    On the wrapper
  </button>
</span>

<!-- Right: the directive sits on the element that actually paints the rounded background. -->
<span style="display: inline-block">
  <button
    type="button"
    gogRipple
    style="
      padding: 12px 20px;
      border: 1px solid var(--gog-border-color);
      background: var(--gog-surface-color);
      color: inherit;
      font: inherit;
      border-radius: 999px;
    "
  >
    On the surface
  </button>
</span>

The library's own components never make you think about this — each opts its own inner element in. The rule applies only to markup you wrote yourself.

It does not clip a badge

This is the reason the ripple is not simply overflow: hidden on the host. gogBadge pins its badge outside the host's box with negative insets, so a host that clips its overflow clips the badge with it. The wash lives in a layer that clips itself instead, and the host is never given overflow: hidden at all — press these and the badge stays whole.

<button
  type="button"
  gogRipple
  gogBadge="8"
  badgeAriaLabel="8 unread"
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
    border-radius: var(--gog-radius);
  "
>
  Inbox
</button>
<button
  type="button"
  gogRipple
  gogBadge
  badgeDot
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
    border-radius: 999px;
  "
>
  Dot, top-end
</button>
<button
  type="button"
  gogRipple
  gogBadge="99+"
  badgePosition="bottom-start"
  badgeVariant="info"
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
    border-radius: var(--gog-radius);
  "
>
  Bottom-start
</button>

Theming

Five tokens, and all five are ordinary inherited custom properties — so setting one on the element, or on anything above it, is the per-instance override. There is no variant tier and no ::ng-deep.

--gog-ripple-color defaults to currentColor rather than to a palette token. It is the only token in the catalogue that does, and it is why no per-variant tier is needed: the wash reads as the surface's own foreground on a filled button and a ghost one alike, in every theme.

Accent-coloured wash
Higher opacity
Slower
<!-- Ordinary inherited custom properties: set one on the element, or anything above it. -->
<div
  gogRipple
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
    border-radius: var(--gog-radius);
    --gog-ripple-color: var(--gog-accent-color);
  "
>
  Accent-coloured wash
</div>
<div
  gogRipple
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
    border-radius: var(--gog-radius);
    --gog-ripple-opacity: 0.55;
  "
>
  Higher opacity
</div>
<div
  gogRipple
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
    border-radius: var(--gog-radius);
    --gog-ripple-enter-duration: 900ms;
    --gog-ripple-exit-duration: 700ms;
  "
>
  Slower
</div>

The library's components — GOG_CONFIG.ripple.enabled

Inside a provideGogConfig with ripple.enabled on, the library's own components ripple; each also takes a ripple input that wins over the config in either direction, and a disabled one stays still. Writing gogRipple on your own element is already a per-element decision, so the config does not apply to it — rippleDisabled takes it back.

gog-chip
<!-- The library's own components, which wire their own ripple: on from the config. -->
<gog-button>gog-button</gog-button>
<gog-chip>gog-chip</gog-chip>
<gog-button variant="outline" [ripple]="false">[ripple]="false"</gog-button>
<gog-button disabled>disabled</gog-button>
<!-- Your own gogRipple is already a per-element decision: the config does not reach it. -->
<button
  type="button"
  gogRipple
  rippleDisabled
  style="
    padding: 12px 20px;
    border: 1px solid var(--gog-border-color);
    background: var(--gog-surface-color);
    color: inherit;
    font: inherit;
    border-radius: var(--gog-radius);
  "
>
  gogRipple rippleDisabled
</button>

It is off by default

21.6.1 wires the ripple into nine of the library's own components and ships it switched off. If you copy an example from this page onto a gog-button and see nothing happen, you have not made a mistake — the app-wide switch is off. Turn it on once:

typescript
import { provideGogConfig } from '@guildofgleks/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideGogConfig({ ripple: { enabled: true } }),
  ],
};

Adding the ripple to the library therefore changed the look of nothing. The demos on this page are the gogRipple directive on the page's own markup, which is always explicit and needs no switch.

The library's own components

You do not put gogRipple on a gog-* component: each one already owns the element that paints its surface, so it wires its own. Turning on GOG_CONFIG.ripple.enabled gives all nine at once:

  • gog-button
  • [gogButton]
  • gog-button-toggle-group
  • gog-chip
  • gog-tabs
  • gog-accordion
  • gogCollapsibleTrigger
  • gogMenuItem
  • gog-select / gog-multiselect / gog-autocomplete options

Each also takes a ripple input that wins over the app-wide setting in both directions — one instance can opt out of an app-wide on, or opt in without the app switching over.

This is the first visual default that lives in GOG_CONFIG rather than in theme.css, which is a deliberate exception to that boundary: a token could hide the wash, but the element, its listeners and its frames would still be paid for. A real "off" has to reach the TypeScript.

Accessibility

Decoration and nothing else.

  • Nothing announced — the wash layer is aria-hidden, and the host is not changed in any way assistive tech would notice: no role, no state, no name.
  • Keyboard — Enter and Space on a focused host ripple from its centre; the host's own keyboard behaviour is unchanged.
  • Motion — under prefers-reduced-motion: reduce there is no ripple at all: it is the most purely decorative motion in the library.

API Reference

Inputs

NameTypeDefaultDescription
rippleDisabledbooleanfalseSwitches the effect off. Detaches the listeners and drops the host class rather than ignoring events, so a disabled ripple costs nothing.
rippleCentredbooleanfalseStarts the wave from the middle instead of from the pointer. Keyboard activation is always centred, because a key press carries no coordinates.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.ripple.enabled — turns the press ripple on app-wide for nine other components — see each one’s own section. [gogRipple] on your own element is not covered; the attribute is already the per-element decision.

This site is not on the default here. The library ships ripple.enabled as false; these docs set it to true app-wide so the demos above actually show the press feedback. In a fresh app you get no ripple until you ask for one — the droplet button in the header switches this site between the two, and it is on right now.

Styling Tokens

Every CSS custom property the ripple paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-ripple-colorThe wash. Defaults to currentColor rather than a palette token — the only token in this catalogue that does — so it reads as the surface’s own foreground on a filled surface and a ghost one alike, which is why the ripple needs no per-variant tier.
--gog-ripple-opacityPeak opacity of the wash.
--gog-ripple-enter-durationHow long the wave takes to expand from the press point.
--gog-ripple-exit-durationHow long it fades once the pointer is released.
--gog-ripple-easingEasing curve for both phases.