# Waves.js

######

## Click. Splash. Repeat.

Waves.js is a lightweight JavaScript library that adds a Material Design-inspired ripple effect to UI elements. It creates a subtle, tactile feedback animation when users interact with buttons, cards, and other clickable elements, enhancing the overall user experience with visual confirmation of touch interactions.

Pro Tip: Waves.js works with both mouse and touch events, making it perfect for creating consistent interaction feedback across desktop and mobile interfaces.

## Installation

Include the Waves.js script and CSS in your HTML file:

    <!-- Include Waves CSS -->
    <link rel="stylesheet" href="plugins/waves/waves.min.css">

    <!-- Include Waves JS -->
    <script src="plugins/waves/waves.min.js"></script>

#### Basic initialization

    // Initialize Waves with default options
    document.addEventListener('DOMContentLoaded', function() {
        Waves.init();
    });

    // Or with custom options
    Waves.init({
        duration: 500,
        delay: 200
    });

#### HTML Structure

    <!-- Basic button with waves effect -->
    <button class="waves-effect">Click me</button>

    <!-- Button with waves effect and color -->
    <button class="waves-effect waves-light">Light Effect</button>

    <!-- Other elements with waves effect -->
    <div class="card waves-effect">Card with ripple</div>
    <a href="#" class="waves-effect waves-teal">Teal Ripple Link</a>

Important: The `waves-effect` class is required for any element you want to apply the ripple effect to. Additional classes like `waves-light` or `waves-teal` modify the appearance of the effect.

## Configuration Options

Waves.js offers several configuration options to customize the ripple effect:

Option | Default Value | Description | Type
--- | --- | --- | ---
`duration` | 750 | Duration of the ripple animation in milliseconds. | number
`delay` | 200 | Delay before showing the ripple effect on touch devices, in milliseconds. | number

## CSS Classes

Waves.js uses several CSS classes to control the appearance of the ripple effect:

Class | Description
--- | ---
`waves-effect` | Base class required for any element to have the ripple effect.
`waves-light` | Creates a light-colored ripple (white), ideal for dark backgrounds.
`waves-red`, `waves-yellow`, `waves-orange`, `waves-purple`, `waves-green`, `waves-teal` | Colored ripple effects matching the specified color.
`waves-circle` | Creates a circular ripple effect, ideal for round buttons.
`waves-float` | Adds a subtle floating animation when hovering over the element.
`waves-block` | Makes the ripple effect fill the entire element (useful for block elements).

Pro Tip: You can combine multiple classes for different effects. For example, `waves-effect waves-light waves-circle` creates a light circular ripple effect.

## API Methods

Waves.js exposes several methods for programmatic control:

    // Initialize Waves with options
    Waves.init({
        duration: 500,
        delay: 200
    });

    // Attach Waves effect to elements
    Waves.attach('.my-button');
    Waves.attach('.my-card', ['waves-light', 'waves-block']);

    // Programmatically create a ripple
    Waves.ripple(document.querySelector('.my-button'), {
        wait: 1000,                // Wait 1000ms before hiding the ripple
        position: {x: 20, y: 20}   // Position of the ripple (default is center)
    });

    // Remove all ripples from elements
    Waves.calm('.my-button');

#### Method Details

Method | Parameters | Description
--- | --- | ---
`Waves.init(options)` | `options`: Object with configuration options | Initializes Waves.js with the specified options.
`Waves.attach(elements, classes)` | `elements`: DOM element, selector, or array of elements `classes`: String or array of additional classes | Attaches the Waves effect to the specified elements with optional additional classes.
`Waves.ripple(elements, options)` | `elements`: DOM element, selector, or array of elements `options`: Object with ripple options (wait, position) | Programmatically triggers a ripple effect on the specified elements.
`Waves.calm(elements)` | `elements`: DOM element, selector, or array of elements | Removes all ripples from the specified elements.
`Waves.displayEffect(options)` | `options`: Object with configuration options | Deprecated. Use `Waves.init()` instead.

## Special Elements Handling

Waves.js includes special handling for certain HTML elements:

#### Input Elements

    <!-- Input with waves effect -->
    <input type="button" class="waves-effect" value="Input Button">

When applied to `<input>` elements, Waves.js automatically wraps the input in a container to properly display the ripple effect.

#### Image Elements

    <!-- Image with waves effect -->
    <img src="image.jpg" class="waves-effect" alt="Image with ripple">

Similar to inputs, images are wrapped in a container to properly display the ripple effect.

Note: For SVG elements, Waves.js has special handling to ensure the ripple effect works correctly.

## Touch Device Handling

Waves.js includes sophisticated touch event handling to ensure a smooth experience on mobile devices:

    // Touch handling in Waves.js
    var TouchHandler = {
        touches: 0,

        allowEvent: function(e) {
            var allow = true;

            if (/^(mousedown|mousemove)$/.test(e.type) && TouchHandler.touches) {
                allow = false;
            }

            return allow;
        },

        registerEvent: function(e) {
            var eType = e.type;

            if (eType === 'touchstart') {
                TouchHandler.touches += 1; // push
            } else if (/^(touchend|touchcancel)$/.test(eType)) {
                setTimeout(function() {
                    if (TouchHandler.touches) {
                        TouchHandler.touches -= 1; // pop after 500ms
                    }
                }, 500);
            }
        }
    };

Key features of the touch handling include:

- Touch and mouse event coordination: Prevents duplicate events when both touch and mouse events are triggered
- Delay for touch devices: Adds a configurable delay before showing the ripple on touch devices
- Touch movement detection: Cancels the ripple effect if the user moves their finger (for scrolling)
- Multi-touch support: Properly handles multiple simultaneous touches

## Usage Examples

#### Basic Buttons

    <!-- Default ripple effect -->
    <button class="btn waves-effect">Default</button>

    <!-- Light ripple effect (for dark backgrounds) -->
    <button class="btn btn-dark waves-effect waves-light">Light Effect</button>

    <!-- Colored ripple effects -->
    <button class="btn waves-effect waves-red">Red Effect</button>
    <button class="btn waves-effect waves-yellow">Yellow Effect</button>
    <button class="btn waves-effect waves-orange">Orange Effect</button>
    <button class="btn waves-effect waves-purple">Purple Effect</button>
    <button class="btn waves-effect waves-green">Green Effect</button>
    <button class="btn waves-effect waves-teal">Teal Effect</button>

#### Cards and Panels

    <!-- Card with ripple effect -->
    <div class="card waves-effect">
        <div class="card-body">
            This entire card has a ripple effect
        </div>
    </div>

    <!-- Panel with block ripple effect -->
    <div class="panel waves-effect waves-block">
        <div class="panel-heading">Panel Title</div>
        <div class="panel-body">
            This panel has a block ripple effect
        </div>
    </div>

#### Circular Buttons

    <!-- Circular button with ripple effect -->
    <button class="btn btn-circle waves-effect waves-circle">
        <i class="fa fa-plus"></i>
    </button>

    <!-- Circular button with light ripple effect -->
    <button class="btn btn-dark btn-circle waves-effect waves-circle waves-light">
        <i class="fa fa-check"></i>
    </button>

#### Dynamic Attachment

    // Dynamically add waves effect to elements created after page load
    document.addEventListener('DOMContentLoaded', function() {
        // Initialize Waves
        Waves.init();

        // Create a new button
        var button = document.createElement('button');
        button.textContent = 'Dynamic Button';
        document.body.appendChild(button);

        // Attach waves effect to the new button
        Waves.attach(button, ['waves-light']);

        // Attach to multiple elements with additional classes
        Waves.attach('.dynamic-elements', ['waves-green', 'waves-float']);
    });

## Best Practices

- Apply the ripple effect only to interactive elements that users can click or tap
- Use appropriate colors for the ripple effect that complement your UI design
- For dark-colored elements, use the `waves-light` class for better visibility
- For circular buttons, use the `waves-circle` class for a more natural-looking effect
- Initialize Waves.js after the DOM is fully loaded to ensure all elements are properly processed
- For dynamically created elements, use `Waves.attach()` to add the ripple effect
- Consider using `waves-float` for elements that should have additional hover feedback

Pro Tip: For the best user experience, keep the ripple effect subtle and quick. A duration of 500-750ms is usually ideal for most interfaces.

## Browser Support

Waves.js supports all modern browsers including:

- Chrome
- Firefox
- Safari
- Edge
- Opera
- Mobile browsers (iOS Safari, Android Chrome)

For older browsers like IE11, Waves.js includes fallbacks to ensure basic functionality.

Note: For optimal performance on mobile devices, consider adjusting the `duration` and `delay` options to match the responsiveness of your target devices.

## Troubleshooting

Common Issues:

- Ripple effect not showing? Ensure the element has the `waves-effect` class and is properly initialized.
- Ripple effect not visible on dark elements? Add the `waves-light` class for better contrast.
- Effect not working on dynamically created elements? Use `Waves.attach()` after creating the elements.
- Ripple effect looks distorted? For non-rectangular elements, try adding the `waves-circle` class.
- Performance issues on mobile? Reduce the `duration` value when initializing Waves.js.

##### On This Page

- Introduction
- Installation
- Configuration
- CSS Classes
- API Methods
- Special Elements
- Touch Handling
- Usage Examples
- Best Practices
- Browser Support
- Troubleshooting

#### Hi Sunny,

how can I help you today?
Analyze my data

Create a new report

Summarize my Calendar

App Builder
Unlock limitless design potential with 16+ layout combinations and extensive customization options—tailor your dashboard to fit your exact needs.
Header position fixed
Navigation full height
Navigation position fixed
Navigation collapsed
Navigation Minified
Dark Navigation
Colorblind Mode
High Contrast Mode