reactive-hermes
v1.1.7
Published
A notification manager for react. Animated, customizable, light and cleaner, allows you to controll duration, sound, and even use other react components inside of messages.
Downloads
5
Maintainers
Readme
Hermes, the notifier
Hermes is a notification message manager.
It deals with your messages in your page's interface.
It manages multiple messages at a time.
It's cleaner, ligher.
It allows you to use react components within the message, making it a powerfull tool.
It can be used to replace other messagers. Has a lighter, malleable design and animations.
You can even manage messages by id or simulate a loading controller.
Take a look.
See how to do this in the examples below.
Test it live, in the demo tool.
Installing
npm install --save reactive-hermes
Using it
You need to import and add the HermesComponent
to your interface.
You should do that once, let's say, in your root page for example.
// used only once
import { Hermes, HermesComponent } from 'reactive-hermes'
[...]
<HermesComponent />
Now, you can access the global Hermes
object, or import it in your modules and then use its API, described below.
// used anywhere
import { Hermes } from 'reactive-hermes'
// or
import Hermes from 'reactive-hermes'
[...]
Hermes.message('The message')
// or
window.Hermes.message('The message') // does not require to be imported
API
Let's see some of the cool things you can do with it!
Props
You can send some props to enforce a default behavior:
- defaultDuration: An integer representing the duration of the message in seconds. By default, it will not close itself.
- updateTitleCounter: Boolean. If present, will update the page's title adding the number of open notifications. Like
(2) Page Title
. - playAudio: Boolean/AudioObject. You can simply use the
playAudio
attribute in the tag to use a default audio or pass a value to it with an Audio Object (to customize the audio). - animate: Animates all the message icons, except for messages that overwrite it.
<HermesComponent
defaultDuration={999}
updateTitleCounter
playAudio={new Audio(...)}
animate />
Methods
These are methods you can access at Hermes
:
Hermes.message(String)
This is an easy way to show a message.Hermes.message(Object)
This is the advanced way to show messages.
It accepts an object with:- type: It may be
default
,warn/warning
,error/fail
,info
orsuccess
- body: This is the message itself. It may be a ReactComponent or a String
- [id]: An optional id for the message
- [playAudio]: Overwrites the global
playAudio
attribute for this particular message. May betrue/false
or an AudioObject - [duration]: The duration in seconds for the message to close itself. This will overwrite the defaultDuration global attribute.
- [locked]: Hides the "x" button to close the message. Requires an
id
. May only be closed programatically - [animate]: Enabled the animation for the message icon
- type: It may be
Hermes.updateMessage(Object)
Allows you to update an existing message. If the message is not opened, it will be shown.
The object must have anid
for the message to be updated.Hermes.closeMessage(String/Number)
Closes an open message with the givenid
Aliases
Aliases work just like the methods, but using different default values.
- Hermes.info(message[, options])
Equivalent to useHermes.message
passing type 'info'. - Hermes.warn(message[, options]) OR Hermes.warning(message[, options])
Equivalent to useHermes.message
passing type 'warn'. - Hermes.error(message[, options]) OR Hermes.fail(message[, options])
Equivalent to useHermes.message
passing type 'error'. - Hermes.success(message[, options])
Equivalent to useHermes.message
passing type 'success'.
Events
You can use this events in the one tag for the HermesComponent, so, the listener will be called everytime any message triggers the given event. Or you can pass the eventListener on each individual message to listen for only its event.
- onMessageOpen: Will be trigger after ending the message animation for showing the message.
- onMessageClose: Will be trigger after ending the message animation for closing the message.
- onMessageUpdate: Will be trigger after updating a message.
- onInfo: Triggered when a message of type
info
is shown. - onWarn: Triggered when a message of type
warn
is shown. - onError: Triggered when a message of type
error
is shown. - onSuccess: Triggered when a message of type
success
is shown.
Compatibility
Are you using methods like showWarning
and showSuccess
?
No problem, you can just import them from Hermes
too!
import { showerror, showSuccess } from 'reactive-hermes'
Examples
See some ways you can show messages
Showing a success message:
let message = 'You are the chosen one.';
Hermes.success(message);
Hermes.success(message, { /* other options */ });
Hermes.message({
type: 'success',
body: message
})
Result:
Showing a warning:
let message = 'You have been warned!';
Hermes.warn(message);
// show the warning, animating its icon
Hermes.warn(message, { animate: true });
Hermes.message({
type: 'warn',
body: message
})
Result:
Showing an error:
let message = 'Something is out of order!';
Hermes.fail(message);
Hermes.error(message);
Hermes.error(message, { /* options */ });
Hermes.message({
type: 'error',
body: message
})
Result:
Showing an info:
let message = 'Info messages, wohoo!!';
Hermes.info(message);
// show info and play audio
Hermes.info(message, { playAudio: true });
Hermes.message({
type: 'info',
body: message
})
Result:
Showing a locked message:
let message = 'Yet another useless message';
Hermes.message({
body: message,
id: 'myMessageId',
locked: true
})
Result:
Updating a message programatically:
let message = 'Saving...';
Hermes.message({
body: message,
id: 'savingMsg',
locked: true,
animate: true
})
Then, some time later...
Hermes.updateMessage({
body: 'Saved',
id: 'savingMsg',
locked: true,
animate: false,
duration: 3 // 3 seconds
})
Result:
Showing message containing a ReactComponent:
Hermes.message(<div>Content here :)</div>)
// or
Hermes.message({
// ...
body: <SomeComponent prop1={val} />
// ...
})
Result:
Customizing styles
You can add changes to the following CSS selectors:
- #hermes-container: The container in which all the messages will be appended to
- .hermes-notif: Each of the notifications
- .hermes-remove-message: The
x
button in unlocked messages, to close them - .hermes-error/.hermes-warn/.hermes-info/.hermes-default: Same as .hermes-notif, but selected by message type
Contributing
Feel free to contribute to this project by sending Pull Requests, reporting problems or even sending suggestions.
Just remember to follow the community terms/rules/good practices :)
How to contribute
Once you've cloned the project...
Install:npm install
Start the server (this will also enable the live/hot reload for the component):npm start
Make chages:
Work in the src/
files, or in the demos/src/
files, or in css/
files.
Build:
npm run build
Then push it and open a PR :)