@dolaanpls/react-awesome-button

# React <AwesomeButton /> UI Component [![Travis](https://img.shields.io/travis/rcaferati/react-awesome-button/master.svg)](https://travis-ci.org/rcaferati/react-awesome-button) ![NPM](https://img.shields.io/npm/v/react-awesome-button.svg) `react-awesome-button` is a performant, extendable, highly customisable, production ready React Component that renders an animated set of 3D UI buttons. Bundled together with a _social share_ and _progress enabled_ components. [<img width="480" alt="react-awesome-button demo" src="https://caferati.me/images/awesome-button.gif">](https://awesome-button.caferati.me) ## Key Features - 60fps 3D animated button - Animated **progress** button - **Social icons** and network specific **share methods** - OnPress ripple effect - Look and feel customisable and extendable in two ways: via **CSS custom properties** or **SASS** variables and lists ([scss config file](https://github.com/rcaferati/react-awesome-button/blob/master/src/styles/default.scss)). - Use it with **CSSModules** or \*\*Plain CSS ## Live demo Checkout the live demo with the `CSS customizer` at <a title="React Awesome Button - CSS Customizer" href="https://awesome-button.caferati.me/" target="_blank">awesome-button.caferati.me</a>. [<img src="https://caferati.me/images/github/awesome-button-web.png" width="800" />](https://awesome-button.caferati.me) ## Figma File Import it directly into your [Figma](https://www.figma.com/file/Ug8sNPzmevU3ZQus9Klu5aHq/react-awesome-button-theme-blue) project. [<img src="https://caferati.me/images/github/figma-awesome-button.png" width="800" />](https://www.figma.com/file/Ug8sNPzmevU3ZQus9Klu5aHq/react-awesome-button-theme-blue) You can run the storybook locally on `6006` by cloning this repository and running `npm run storybook` ## Installation ``` npm install --save react-awesome-button ``` ## Styling with plain CSS and CSS Modules ### Plain CSS ```jsx import { AwesomeButton } from 'react-awesome-button'; import 'react-awesome-button/dist/styles.css'; function Button() { return <AwesomeButton type="primary">Button</AwesomeButton>; } ``` ### CSS Modules ```jsx import { AwesomeButton } from 'react-awesome-button'; import AwesomeButtonStyles from 'react-awesome-button/src/styles/styles.scss'; function Button() { return ( <AwesomeButton cssModule={AwesomeButtonStyles} type="primary"> Button </AwesomeButton> ); } ``` ### `AwesomeButton` rendered with a button tag Renders the component with a `button` HTML tag and an `onPress` prop called on animation release. ```jsx import { AwesomeButton } from 'react-awesome-button'; import AwesomeButtonStyles from 'react-awesome-button/src/styles/styles.scss'; function Button() { return ( <AwesomeButton cssModule={AwesomeButtonStyles} type="primary" onPress={() => { // do something }}> Button </AwesomeButton> ); } ``` ### `AwesomeButton` rendered with an anchor tag Render the component with an `anchor` HTML tag setting the `href` attribute. ```jsx import { AwesomeButton } from 'react-awesome-button'; import AwesomeButtonStyles from 'react-awesome-button/src/styles/styles.scss'; function Button() { return ( <AwesomeButton cssModule={AwesomeButtonStyles} type="primary" href="https://google.com"> Button </AwesomeButton> ); } ``` ### `AwesomeButton` props | Attribute | Type | Default | Description | | :------------- | :----------: | :-------: | :------------------------------------------------------------------------------------------------------- | | type | `string` | `primary` | Render a specific button type, styled by the `.scss` type list | | size | `string` | `auto` | Render a specific button size, styled by the `.scss` size list | | element | `node` | `null` | Overwrites the default container element renderer, useful for using it with react-router Link component. | | disabled | `bool` | `false` | Render the disabled button | | visible | `bool` | `true` | Toggle button visibility | | ripple | `bool` | `false` | Sets up the button with the onPress ripple effect | | placeholder | `bool` | `true ` | Should render the animated placeholder on empty `children` | | onPress | `function` | `null` | Default `pressRelease` event function | | onPressed | `function` | `null` | Event function triggered only on full button press | | onReleased | `function` | `null` | Event function triggered on button full animation release | | onMouseDown | `function` | `null` | Event function coupled with the element's `onMouseDown` | | onMouseUp | `function` | `null` | Event function coupled with the element's `onMouseUp` | | href | `string` | `null` | Forces the button to be rendered on an `anchor` container and sets the href to the specified value | | className | `string` | `null` | Adds a `className` to the button container element | | style | `object` | `null` | Passes a `style` object to the container element | | containerProps | `object` | `null` | Exposes an option for freely adding props to the button container element | | cssModule | `object` | `null` | Accepts a css module configuration from the themed `module.scss` files | | target | `string` | `null` | When used together with `href` renders an anchor with a specific target attribute | | before | `React.Node` | `null` | Render a `node` before the main content `span` container; useful for setting icons | | after | `React.Node` | `null` | Render a `node` after the main content `span` container; useful for setting icons | | between | `string` | `null` | Sets the content elements relation to `space-between`; useful for setting icons | | active | `bool` | `false` | When set to `true` activates the pressIn animation | ### `AwesomeButtonProgress` basic example Checkout this example live on the [storyboard](https://caferati.me/demo/react-awesome-button/storybook/?selectedKind=AwesomeButtonProgress&selectedStory=Success). ```jsx import { AwesomeButtonProgress } from 'react-awesome-button'; import AwesomeButtonStyles from 'react-awesome-button/src/styles/styles.scss'; function Button() { return ( <AwesomeButtonProgress cssModule={AwesomeButtonStyles} type="primary" onPress={(event, release) => { // do a sync/async task then call `release()` }}> Button </AwesomeButtonProgress> ); } ``` ### `AwesomeButtonProgress` specific props Being a wrapper on the **`AwesomeButton`** component, it accepts its props plus the following ones. | Attribute | Type | Default | Description | | :----------- | :--------: | :--------: | :------------------------------------------------------------------------------- | | onPress | `function` | `null` | Default `onPress` function returning the `event` and a button `release` strategy | | loadingLabel | `string` | `Wait ..` | Progress button loading label text | | resultLabel | `string` | `Success!` | Progress button success label text | | releaseDelay | `number` | 500 | Delay for releasing the button after the progress animation | ### `AwesomeButtonSocial` basic example If nothing is passed on the `sharer` prop, the component automatically gets the page's own `title` and `og:image` properties; otherwise, it's setup by the `sharer`. ```jsx import { AwesomeButtonSocial } from 'react-awesome-button'; import AwesomeButtonStyles from 'react-awesome-button/src/styles/styles.scss' function Button() { return ( <AwesomeButtonSocial cssModule={AwesomeButtonStyles} type="facebook" sharer={{ url="https://caferati.me" }} > Button </AwesomeButton> ); } ``` ### `AwesomeButtonSocial` whatsapp example ```jsx import { AwesomeButtonSocial } from 'react-awesome-button'; import AwesomeButtonStyles from 'react-awesome-button/src/styles/styles.scss' function Button() { return ( <AwesomeButtonSocial cssModule={AwesomeButtonStyles} type="whatsapp" sharer={{ phone: '############', message: 'Whatsapp init message' }} > Button </AwesomeButton> ); } ``` ### `AwesomeButtonSocial` specific props Being a wrapper on the **`AwesomeButton`** component, it accepts its props plus the following ones. | Attribute | Type | Default | Description | | :------------- | :--------------------: | :-----: | :------------------------------------------------------------------------------------------------------------------------------------------ | | type | `string` | `null` | Render a button type (Facebook, Instagram, Twitter, Github, Youtube, Linkedin, Pinterest, Reddit, Messenger, Whatsapp) | | icon | `bool` or `Dimensions` | `true` | Setting to `false` avoids icon rendering; if the dimensions type is passed in `{width: number, height: number}`, configures the button size | | sharer.url | `string` | `null` | Url string to be used on the sharer | | sharer.image | `string` | `null` | Image url to be rendered on the sharer | | sharer.message | `string` | `null` | Message string to be rendered on the shared post | | sharer.phone | `string` | `null` | Phone number to be used when using the `Whatsapp` sharer type | | sharer.user | `string` | `null` | Username to be redirected when using the `Messenger` sharer type | ## React Native Version Checkout the React Native version of the Awesome Button UI Component at [rcaferati/react-native-really-awesome-button](https://github.com/rcaferati/react-native-really-awesome-button) <img width="280" src='https://caferati.me/images/demo-button-cartman.gif' /> ## Author #### Rafael Caferati - Checkout my <a href="https://caferati.me" title="Full-Stack Web Developer, UI/UX Javascript Specialist" target="_blank">Full-Stack Web Developer Website</a> - Other open source projects @ <a title="Web Software Developer Code Laboratory" target="_blank" href="https://caferati.me/labs">Code Laboratory</a> - A scope of my work @ <a title="Web Software Developer Portfolio" target="_blank" href="https://caferati.me/portfolio">Web Developer Portfolio</a> ## License MIT. Copyright (c) 2019 Rafael Caferati.