react-node-waves v1.0.0

react-md-waves (v. 1.0.0)

react-md-waves is a simple wrapper around Waves that creates reusable ReactJS components to assist in the development of your new web application!

Getting Started

To begin using react-md-waves, execute the following NPM command inside your project directory:

$ npm install --save react-md-waves

Once the package is successfully installed, you are free to continue reading to learn how to use react-md-waves components in your web application.

React Components

WaveInit

WaveInit is our base component. This component must be added before you may begin using waves in your HTML content. This component is responsible for calling Waves.init(); and, as such, must be included at least once in your application.

It is recommended to include one <WaveInit /> at the top-most level of your application, such as a body container or parent div.

Properties

duration

• The duration of the wave effect (in milliseconds) after an element is clicked
• Type: PropTypes.number
• Default: 500 milliseconds

delay

• Delay of showing the waves effect on touch & hide if the user scrolls
• Type: PropTypes.number
• Default: 200 milliseconds

Examples

Initialize Waves with default parameters

<WaveInit />

Initialize Wave with duration set to 1000 milliseconds (1 second)

<WaveInit duration={ 1000 } />

Initialize Waves with duration set to 1000 milliseconds (1 second) and delay set to 500 milliseconds (1/2 second)

<WaveInit duration={ 1000 } delay={ 500 } />

Wave

Our next and arguably most important component is Wave. This component is necessary to "attach" your element and provide it with the wave effect itself.

Effect Properties

type (required)

• The type of element that this wave will be present. See here for the official guidelines
• Type: PropTypes.onOf([WaveType.BLOCK, WaveType.BUTTON, WaveType.CIRCLE])

float

• If set to true, the wave will also provide a "floating" effect on the element
• Type: PropTypes.bool

light

• If set to true, the wave will have a light-colored effect rather than the default dark color
• Type: PropTypes.bool

Effect Examples

Adding a default wave to a div (set to 100px by 100px and a blue background color)

const divStyle = {
    backgroundColor: "blue",
    height: "100px",
    width: "100px"
};

<Wave type={ WaveType.BLOCK }>
    <div style={ divStyle } />
</Wave>

Adding a wave plus floating effect to a Bootstrap button

<Wave type={ WaveType.BUTTON } float={ true }>
    <button type={ "button" } className={ "btn btn-success" }>Button A</button>
</Wave>

Adding a wave, float effect, and light color to a FontAwesome icon

<Wave type={ WaveType.CIRCLE } float={ true } light={ true }>
    <FontAwesomeIcon icon={ faUser } />
</Wave>

Now that we have an understanding on how we may apply the wave effect to a couple of elements, we will now visit event handling for our element(s).

Event Properties

onClick

• If a function callback is passed, when the element is clicked, this property will be called
• Type: PropTypes.func
• Callback: function(event, waveId)

waveId

• Each <Wave /> component has a generated waveId. This ID is used for attaching your element to Waves; however, it is also passed back to your onClick listener, if one is supplied. As such, you may provide a custom waveId for better event management.
• Type: PropTypes.string
• Default: As waveId is optional, if one is not provided, then react-md-waves will automatically generate an ID using the WaveType supplied and a randomly generate integer

Event Examples

Adding an onClick listener without a custom waveId

function handleEvent = (event, waveId) => {
    console.log("Element with Wave ID " + waveId + " was clicked.");
}

...

<Wave type={ WaveType.BUTTON }>
    <button type={ "button" } className={ "btn btn-danger" } onClick={ handleEvent }>Don't Click Me</button>
</Wave>

Since no waveId was provided, when this event is called, its generated ID will be returned instead (eg. WB-19).

Adding an onClick listener with a custom waveId (using the handleEvent from above)

<Wave type={ WaveType.BUTTON } onClick={ handleEvent } waveId={ "btnDontClick" }>
    ...
</Wave>

Now, since we've supplied our component with a custom waveId, once handleEvent is fired, it will pass along "btnDontClick" in place of waveId within the function.

License

Waves is developed and maintained by Alfiana E. Sibuea.

react-md-waves is developed and maintained by James D. Coon.