react-awesome-button:
Build Animated Buttons
That Actually Look Great
A no-nonsense guide to installing, configuring, and customising the most
satisfying React button component in the ecosystem —
complete with loading states, themes, and real-world examples.
📐 Semantic Core
Primary keywords
React animated button
React button component
React button library
Secondary / long-tail
react-awesome-button installation
react-awesome-button setup
react-awesome-button example
react-awesome-button customization
react-awesome-button loading
react-awesome-button states
React button animations
React button styles
React interactive button
LSI phrases
animated CTA React
rab-component
React UI button effects
next() callback button
button theme CSS variables
React button disabled state
accessible React button
Why Your React Buttons Deserve Better
Let’s be honest: the default <button> element has the visual charm of a tax form.
You add onClick, slap on some Tailwind classes, and ship it. It works — nobody
argues otherwise — but it doesn’t feel like anything. Users click it and immediately
wonder whether the action registered, whether the API call fired, whether the universe even
noticed. A flat rectangle with a cursor pointer is not user feedback; it’s a polite suggestion.
The react-awesome-button library — a
performant, React animated button component built on CSS custom properties
and hardware-accelerated transforms — fixes that. It ships with a satisfying 3D press effect,
multiple built-in themes, loading and disabled state management, and a dead-simple API that
won’t make you write 300 lines of boilerplate. Think of it as the
React button library that finally respects both your time and your users’
fingers.
This guide walks you through everything: installation, basic usage, theming, loading states,
react-awesome-button customization, and common pitfalls.
By the end you’ll have a production-ready, accessible, beautifully animated
React button component that makes clicking feel like an actual event.
What Makes react-awesome-button Different
The React ecosystem has no shortage of button packages. MUI, Chakra, Ant Design, Mantine —
they all ship button primitives as part of a much larger design system. That’s fine if you
are already locked into one of those ecosystems. But if you want a single, standalone,
React interactive button without pulling in a monolithic peer-dependency
tree, you are usually left building it yourself. react-awesome-button
occupies a precise niche: a zero-design-system dependency, production-grade
React button component with first-class animation support.
3D Press Effect
CSS transform + box-shadow creates a tactile depth illusion on every click — no JavaScript animation loop needed.
GPU-Accelerated
Animations run on transform and opacity — compositor-thread only, 60 fps guaranteed.
Theme System
Import a pre-built theme CSS or override any CSS custom property to match your brand in minutes.
Loading States
Built-in async action callback pattern keeps the button locked until your Promise resolves.
Accessible
Semantic <button> element under the hood with proper ARIA and keyboard support.
Tiny Footprint
~6 KB minified + gzipped. No runtime dependencies beyond React itself.
The library’s philosophy is intentional minimalism: it solves one problem — making
React button animations effortless — without pretending to be a full
component library. You get exactly what you need and nothing you don’t. That philosophy
is reflected in the API, which exposes fewer than a dozen meaningful props, all of them
self-explanatory.
react-awesome-button Installation & Project Setup
Getting react-awesome-button setup
done takes under two minutes. The package is available on npm and works with any
React 16.8+ project — Vite, Create React App, Next.js, Remix, Gatsby — without
configuration magic. The only meaningful prerequisite is a CSS loader in your build
pipeline, which all of the above handle out of the box.
Install the package
Choose your package manager — both work identically.
bash
# npm
npm install --save react-awesome-button
# yarn
yarn add react-awesome-button
# pnpm
pnpm add react-awesome-button Once installed, the package exposes a named export AwesomeButton and several
CSS theme files inside react-awesome-button/dist/themes/. You always need to
import at least one theme — otherwise the component renders with no visual styling.
This separation between logic and style is deliberate: it keeps the JS bundle lean and
lets you swap or override themes without touching component code.
Next.js users: if you import a CSS file inside a page or component and
get a “Global CSS cannot be imported from files other than your Custom App” error,
move the theme import to _app.js / _app.tsx. Alternatively,
use a CSS Module wrapper or a third-party plugin that allows component-level global CSS.
Your First react-awesome-button Example
Below is the minimal working
react-awesome-button example —
nothing exotic, just the component doing what it does best. Notice how little code
is required to get a polished, animated result:
jsx — App.jsx
import React from 'react';
import { AwesomeButton } from 'react-awesome-button';
import 'react-awesome-button/dist/themes/theme-blue.css';
export default function App() {
return (
<AwesomeButton
type="primary"
onPress={() => console.log('Button pressed!')}
>
Click Me
</AwesomeButton>
);
} That’s it. You have a themed, animated, accessible
React interactive button with a 3D press effect. The type
prop maps to a CSS modifier class defined in the theme file — so "primary",
"secondary", "danger", and similar values are available out of
the box depending on which theme you import. The onPress callback fires on
the button’s release (not mousedown), matching the native browser behaviour that users
intuitively expect.
Choosing and Importing the Right Theme
The react-awesome-button library
ships six pre-built themes, each targeting a different visual palette and use-case. They
are pure CSS files with no JavaScript coupling, which means switching themes is a
single line change. All theme files live in
react-awesome-button/dist/themes/ and follow the naming convention
theme-[name].css.
theme-blue.css
theme-red.css
theme-green.css
theme-purple.css
theme-darkblue.css
theme-flat.css
Each theme defines a comprehensive set of CSS custom properties that control everything
from background colour and border radius to shadow depth and animation timing. The
React button styles you see in the browser are entirely driven by these
variables — the component’s JavaScript never hardcodes a colour value. This is not just
elegant architecture; it is what makes react-awesome-button customization
so painless in practice.
If none of the pre-built themes fits your design system, you have two options: override
individual CSS variables after your theme import, or author a full custom theme from
scratch using the existing files as a reference. The second approach makes sense for
design systems with strict brand guidelines; the first is what most developers actually
need — a few colour tweaks, maybe a different border radius, done in five minutes.
css — custom-overrides.css
/* Import base theme first, then override */
:root {
/* Primary button background */
--button-primary-color: #ff6b35;
--button-primary-color-dark: #d4521e;
--button-primary-color-hover: #ff8c5a;
--button-primary-color-active: #c4481a;
/* Shape & sizing */
--button-default-border-radius: 10px;
--button-default-height: 52px;
--button-default-font-size: 1rem;
--button-default-font-weight: 700;
} Open the theme CSS file in node_modules/react-awesome-button/dist/themes/
and copy the variable names you want to override. Every visual property is exposed — you
will rarely need to write any !important overrides if you follow this pattern.
API Reference: Every Prop You Need to Know
The AwesomeButton component keeps its prop surface deliberately narrow.
There are no undocumented escape hatches or confusing prop combinations — each prop
does exactly one thing. Here is the complete reference for the
React button component‘s public API:
| Prop | Type | Default | Description |
|---|---|---|---|
| type | string |
"primary" |
Maps to a CSS modifier. Available types depend on your imported theme (e.g. primary, secondary, danger). |
| onPress | function |
— | Callback fired on button release. For async actions, receives a next function as its argument. |
| disabled | boolean |
false |
Prevents interaction and applies disabled styling. Does not prevent programmatic focus. |
| size | string |
"medium" |
Controls button dimensions. Accepts "small", "medium", "large", "icon". |
| href | string |
— | Renders the button as an anchor (<a>) tag. Combines button styling with navigation semantics. |
| target | string |
— | Equivalent to the HTML target attribute. Only meaningful when href is set. |
| style | object |
— | Inline style override applied to the outer wrapper element. |
| className | string |
— | Additional CSS class names appended to the root element — useful for integration with Tailwind or CSS Modules. |
| element | ReactNode |
— | Renders a custom element inside the button (e.g. an icon component). Takes precedence over children. |
| moveEvents | boolean |
true |
Enables mouse/touch move tracking for the parallax hover effect. Disable on low-power devices if needed. |
One prop deserves extra attention: onPress. Unlike a plain onClick,
it fires when the user releases the button (mouseup / touchend), which aligns with
the platform’s native button behaviour. When you pass an async action, the callback signature
changes slightly — you receive a next function that you must call to resolve the
loading state. This design decision prevents the common bug where a button stays stuck in
“loading” forever because the developer forgot to reset state manually.
react-awesome-button Loading States and Async Actions
Handling async operations cleanly is where most
React button libraries fall flat. The typical pattern — set a
isLoading state variable, conditionally render a spinner, reset on
completion — is fine in isolation but adds noise to every component that uses a button.
react-awesome-button loading
state is handled through a built-in callback pattern that keeps all the state management
inside the component itself.
The mechanism works through the next function passed to your onPress
callback. The moment onPress is called, the button enters a locked loading state —
the 3D press animation holds, a loading indicator appears, and further clicks are silently
ignored. Once your async work is done, you call next() and the button returns
to its resting state. That’s the entire API for loading behaviour. No reducers. No context.
No useState calls. Just a callback.
jsx — AsyncButton.jsx
import { AwesomeButton } from 'react-awesome-button';
import 'react-awesome-button/dist/themes/theme-blue.css';
async function submitToAPI() {
// Simulated API call — replace with your real fetch/axios call
await new Promise((resolve) => setTimeout(resolve, 2000));
}
export default function AsyncButton() {
return (
<AwesomeButton
type="primary"
onPress={async (next) => {
try {
await submitToAPI();
// ✅ Success — resolve the loading state
next();
} catch (err) {
console.error(err);
// ✅ Still resolve — button must not stay frozen
next();
}
}}
>
Submit Form
</AwesomeButton>
);
} Always call next() in your catch block.
If your async function throws and you don’t call next(), the button will
remain locked in its loading state indefinitely. Users will see a frozen button with
no way to retry — a UX catastrophe that is entirely avoidable.
Combining Loading with Disabled State
The disabled prop and the loading state are independent mechanisms.
disabled prevents all interaction from the start — useful when form
validation hasn’t passed yet. The loading state, triggered by entering the
onPress callback, is a temporary lock that automatically releases
when next() is called. You can use both simultaneously: disable the
button by default, enable it when validation passes, and let the loading mechanism
handle the async feedback once the user clicks. Each mechanism serves a distinct
purpose and they compose cleanly without conflicts.
Advanced react-awesome-button Customization
Beyond theme swapping, react-awesome-button customization covers three
levels of depth: CSS variable overrides (covered above), custom class injection via
className, and full theme authoring. The right level depends on how far
your design requirements diverge from the defaults. For most projects, CSS variable
overrides cover 90% of needs. Custom class injection bridges the gap when you need
pixel-level positioning control or integration with a utility-first CSS framework.
Tailwind CSS Integration
Integrating AwesomeButton with Tailwind is straightforward because the
component accepts a className prop. Tailwind utility classes are appended
to the component’s root element, letting you control margin, padding around the button,
responsive sizing, and layout positioning without touching the component’s internal CSS.
Keep in mind that Tailwind classes will not override CSS variables — for colour and
animation changes, you still need the variable approach.
jsx — TailwindIntegration.jsx
<AwesomeButton
type="primary"
className="mx-auto mt-8 w-full md:w-auto"
onPress={() => handleSubmit()}
>
Get Started Free
</AwesomeButton>Icon Buttons and Custom Element Content
The element prop lets you place any React node inside the button’s content
area. This is the cleanest way to add icons — whether from react-icons,
Heroicons, or your own SVG components — without wrapping the button in additional markup.
The button preserves its animation and loading behaviour regardless of what you pass as
element. If you need an icon-only button without text, combine
size="icon" with an appropriate aria-label to maintain
accessibility.
jsx — IconButton.jsx
import { FiArrowRight } from 'react-icons/fi';
// Icon + text button
<AwesomeButton type="primary" onPress={handleContinue}>
<span style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
Continue <FiArrowRight />
</span>
</AwesomeButton>
// Icon-only button
<AwesomeButton
type="primary"
size="icon"
aria-label="Go to next step"
onPress={handleContinue}
>
<FiArrowRight />
</AwesomeButton>
Real-World Patterns: Form Submission, Navigation, and More
Theory is great but production code lives in context. The following patterns address
the most common scenarios you will encounter when integrating
react-awesome-button into a real application. Each pattern is self-contained
and copy-paste ready — adapt the API call and the success handling to your specific use case.
Pattern 1: Form Submission with Validation
The cleanest form submission pattern combines React’s controlled input state with the
disabled prop to gate the button, and the next() callback
pattern to handle the async submission. Validation runs synchronously before the
onPress fires; async submission happens inside the callback. Error handling
triggers next() in both success and failure branches so the button
never freezes.
jsx — ContactForm.jsx
import React, { useState } from 'react';
import { AwesomeButton } from 'react-awesome-button';
import 'react-awesome-button/dist/themes/theme-blue.css';
export default function ContactForm() {
const [email, setEmail] = useState('');
const [status, setStatus] = useState('');
const isValid = email.includes('@') && email.length > 5;
const handleSubmit = async (next) => {
try {
await fetch('/api/subscribe', {
method: 'POST',
body: JSON.stringify({ email }),
headers: { 'Content-Type': 'application/json' },
});
setStatus('✅ Subscribed!');
} catch {
setStatus('❌ Something went wrong');
} finally {
next(); // Always release the button
}
};
return (
<form>
<input
type="email"
value={email}
onChange={(e) => setEmail(e.target.value)}
placeholder="your@email.com"
/>
<AwesomeButton
type="primary"
disabled={!isValid}
onPress={handleSubmit}
>
Subscribe
</AwesomeButton>
{status && <p>{status}</p>}
</form>
);
}Pattern 2: Navigation Button with href
When your button is semantically a link — a CTA that navigates to another page — use the
href prop. The component renders as an <a> tag under the
hood, preserving all button styles and animations while delivering correct HTML semantics.
This matters for accessibility, SEO (Google can follow <a> tags but treats
click-handled <div>s with suspicion), and right-click / middle-click
behaviour that users expect from links.
jsx — CTASection.jsx
<AwesomeButton
type="primary"
size="large"
href="https://yourapp.com/signup"
target="_blank"
>
Start Free Trial →
</AwesomeButton>
Performance Considerations and Accessibility
React button animations done poorly are a performance tax. Animated
properties that trigger layout recalculation — width, height,
top, left, margin — force the browser to re-run
its layout algorithm on every animation frame, resulting in janky 30fps experiences on
mid-range devices. react-awesome-button‘s animations are architected
to avoid this entirely: every visual effect uses transform and
opacity, which run exclusively on the browser’s compositor thread and never
trigger layout or paint.
The moveEvents prop (enabled by default) powers a subtle parallax tilt effect
as the cursor moves over the button. On desktop this adds a satisfying depth perception cue.
On lower-end Android devices or in battery-saving modes, this hover tracking adds marginal
event-listener overhead. If you are building for a performance-constrained audience, you can
disable it with moveEvents={false} — you lose the parallax effect but the
press animation remains intact.
On the accessibility front, the component renders a semantic <button>
element (or <a> when href is set), responds to keyboard
Enter and Space keys, and applies the disabled attribute correctly when the
prop is set. The one thing it does not do automatically is manage ARIA live regions for
async state announcements — if screen reader users need to know the button is loading or
has succeeded, add an aria-live region adjacent to the button and update
its content based on your async state.
always provide descriptive
children text or an aria-labelfor icon-only buttons; confirm keyboard navigability by tabbing through your page;
verify colour contrast meets WCAG AA (4.5:1) against your custom theme colours;
and test disabled state behaviour with a screen reader.
Common Issues and How to Fix Them
Even a well-documented library produces head-scratching moments when it meets the
real world. Here are the issues developers hit most frequently when working through a
react-awesome-button tutorial
for the first time — along with direct fixes.
Button renders with no styles (plain HTML button appearance)
You forgot the theme CSS import. Add
import 'react-awesome-button/dist/themes/theme-blue.css'
(or any other theme) to the file where the component is used, or to your
global stylesheet entry point.
Button stays permanently in loading state
You are not calling next() after your async operation completes —
especially in error paths. Wrap your async logic in a try/catch/finally
and call next() inside finally to guarantee it runs.
Next.js throws “Global CSS cannot be imported” error
Move the theme CSS import to pages/_app.js or
app/layout.tsx (App Router). Alternatively, wrap the import in a
CSS Module that re-exports the global styles, or use
next-transpile-modules configuration.
CSS custom property overrides not applying
Make sure your override CSS loads after the theme file. If you import
both in the same file, order your imports: theme first, overrides second.
CSS specificity should not be an issue with root-level custom property overrides,
but import order always matters.
TypeScript type errors on onPress callback
The package ships TypeScript definitions. The correct type for the async
onPress callback is
(next: () => void) => void | Promise<void>.
If you see type errors, ensure you’re on a recent version of the package
and that @types/react is installed.
Complete react-awesome-button Example: A CTA Landing Section
Let’s put everything together into a realistic landing page CTA section that demonstrates
multiple button types, sizes, loading state, and custom styling — the kind of component
you’d actually ship in a product. This is not a toy demo; it’s a starting point for
production use.
jsx — CTASection.jsx (complete)
import React, { useState } from 'react';
import { AwesomeButton } from 'react-awesome-button';
import { FiZap, FiArrowRight, FiGithub } from 'react-icons/fi';
import 'react-awesome-button/dist/themes/theme-blue.css';
import './cta-overrides.css'; // your CSS variable overrides
async function handleSignup(email) {
const res = await fetch('/api/signup', {
method: 'POST',
body: JSON.stringify({ email }),
headers: { 'Content-Type': 'application/json' },
});
if (!res.ok) throw new Error('Signup failed');
return res.json();
}
export default function CTASection() {
const [email, setEmail] = useState('');
const [message, setMessage] = useState('');
const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
return (
<section className="cta-wrapper">
<h2>Start building in minutes</h2>
<div className="button-row">
{/* Primary CTA — async signup */}
<AwesomeButton
type="primary"
size="large"
disabled={!isValidEmail}
onPress={async (next) => {
try {
await handleSignup(email);
setMessage('🎉 Welcome aboard!');
} catch {
setMessage('❌ Please try again.');
} finally {
next();
}
}}
>
<FiZap /> Get Started Free
</AwesomeButton>
{/* Secondary CTA — navigation link */}
<AwesomeButton
type="secondary"
size="large"
href="https://github.com/your-repo"
target="_blank"
>
<FiGithub /> View on GitHub
</AwesomeButton>
</div>
{message && (
<p role="status" aria-live="polite">
{message}
</p>
)}
</section>
);
} The aria-live="polite" region on the status paragraph handles screen reader
announcements for async state changes. The role="status" attribute provides
an additional semantic hint. Neither costs you anything in terms of visual design — they
are invisible to sighted users — but they make the difference between an accessible and
an inaccessible async interaction for assistive technology users.
Frequently Asked Questions
How do I install react-awesome-button in a React project?
Run npm install --save react-awesome-button (or
yarn add react-awesome-button) in your project root. Then in your
component file, import the component and a theme CSS:
import { AwesomeButton } from 'react-awesome-button';
import 'react-awesome-button/dist/themes/theme-blue.css';
That’s the complete
react-awesome-button installation.
No additional configuration is required for Vite, Create React App, or Webpack-based projects.
Next.js users should move the CSS import to _app.js or
app/layout.tsx.
Can I customize the react-awesome-button styles to match my brand?
Yes — and it’s easier than you might expect. The entire visual system is driven by
CSS custom properties defined in the theme file. To override them, add a
:root { } block in any CSS file that loads after the theme, and
redefine the variables you want to change. Key variables include
--button-primary-color, --button-primary-color-dark,
--button-default-border-radius, and
--button-default-height.
For Tailwind integration, use the className prop to add utility classes
for layout and spacing. For full brand-aligned themes, copy an existing theme CSS file
from node_modules/react-awesome-button/dist/themes/ and modify every
variable to create a fully custom theme.
Does react-awesome-button support loading and disabled states?
Yes, both are first-class features. The loading state is triggered
automatically when your onPress callback is invoked — the button locks,
displays a loading indicator, and ignores further clicks until you call the
next() function passed as the callback’s argument. Always call
next() in a finally block to ensure the button releases
even on errors.
The disabled state is controlled by the disabled prop.
Set it to true to prevent all interaction and apply disabled styling.
Both states are independent and can be used together — for example, disable the button
during form validation and let the loading mechanism handle async submission feedback.
Ready to Ship Better Buttons?
You now have everything you need to integrate, customise, and confidently ship
react-awesome-button in production. Go make something users actually
enjoy clicking.