React Gradient Hover

A React component that creates an interactive gradient effect following mouse movement on hover. The gradient smoothly animates and creates a spotlight effect that follows the cursor.

Features

• 🎨 Smooth gradient animation that follows mouse movement
• 🎯 Customizable gradient colors
• ⚡ High-performance animations using requestAnimationFrame
• 🔧 Flexible component API with TypeScript support
• 📱 Responsive and works on all screen sizes
• 🎪 Smooth return-to-center animation on mouse leave

Installation

npm install react-gradient-hover

or

yarn add react-gradient-hover

Live Demo

Check out the live demo to see the component in action!

Usage

Basic Example

import { GradientHover } from 'react-gradient-hover';

function App() {
  return (
    <GradientHover>
      <div style={{ padding: '2rem' }}>
        <h2>Hover over me!</h2>
        <p>The gradient will follow your mouse movement.</p>
      </div>
    </GradientHover>
  );
}

Custom Colors

<GradientHover colors={['#ff6b6b', '#4ecdc4']}>
  <div style={{ padding: '2rem' }}>
    <h2>Custom gradient colors</h2>
  </div>
</GradientHover>

Advanced Configuration

<GradientHover
  colors={['#667eea', '#764ba2']}
  animationSpeed={0.02}
  borderRadius="20px"
  transitionDuration={0.5}
  activeOverlayOpacity={0.1}
  className="my-custom-class"
  onClick={() => console.log('Clicked!')}
>
  <div style={{ padding: '3rem' }}>
    <h2>Advanced Configuration</h2>
    <p>With custom properties and click handler</p>
  </div>
</GradientHover>

Hide Gradient Until Hover

<GradientHover
  colors={['#ff6b6b', '#4ecdc4']}
  shouldAlwaysShowGradient={false}
>
  <div style={{ padding: '2rem' }}>
    <h2>Hidden Gradient</h2>
    <p>The gradient will only appear when you hover over this component</p>
  </div>
</GradientHover>

API

Props

Styling

The component is fully customizable through props! All visual aspects can be controlled by passing the appropriate props:

<GradientHover
  colors={['#custom-color-1', '#custom-color-2']}
  borderRadius="20px"
  transitionDuration={2}
  activeOverlayOpacity={0.1}
  shouldAlwaysShowGradient={true}
  animationSpeed={0.02}
>
  {/* Your content */}
</GradientHover>

Advanced CSS Customization

If you need additional styling beyond the available props, you can target the component with CSS:

.gradient-hover {
  /* Your custom styles */
}

.gradient-hover--is-hovering {
  /* Styles applied during hover */
}

The component uses CSS custom properties internally, which are set from the props you pass.

Browser Support

This component uses modern CSS features including:

• CSS custom properties
• inset property

Make sure your target browsers support these features or provide appropriate fallbacks.

Development

Prerequisites

• Node.js (version 16 or higher)
• npm or yarn

Install dependencies

npm install

Development Workflow

Build the package

npm run build

This creates the distribution files in the dist/ directory:

• dist/index.js - CommonJS bundle
• dist/index.esm.js - ES Module bundle
• dist/index.d.ts - TypeScript declarations

Run the example in development mode

npm run example

This starts a development server with the example app at http://localhost:5173

Build the example for production

npm run example:build

GitHub Pages Deployment

The example site is automatically deployed to GitHub Pages when you push to the main branch. The deployment is handled by GitHub Actions.

Manual deployment

If you need to deploy manually:

1. Build the example site:

   npm run example:build

2. The built files will be in the example-dist/ directory

3. You can then upload these files to GitHub Pages through your repository settings

GitHub Pages URL

Once deployed, your example site will be available at: https://areknow.github.io/react-gradient-hover/

Code Quality

Run linting

npm run lint

Run linting with auto-fix

npm run lint:fix

Format code

npm run format

Check formatting

npm run format:check

Type checking

npm run typecheck

Testing Before Publishing

Dry run package creation

npm pack --dry-run

This shows what files will be included in the published package without actually creating the tarball.

Test the package locally

npm pack
npm install ./react-gradient-hover-1.0.0.tgz

This creates a local tarball and installs it to test the package before publishing.

Publishing to npm

1. Login to npm (if not already logged in)

npm login

2. Check if you're logged in

npm whoami

3. Check if the package name is available

npm view react-gradient-hover

If you get a 404 error, the name is available. If you get package details, the name is taken.

4. Update version (if needed)

npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0  
npm version major  # 1.0.0 -> 2.0.0

5. Build and publish

npm publish

This will automatically:

• Run the build process (via prepublishOnly script)
• Create the package tarball
• Upload to npm registry

6. Verify the published package

npm view react-gradient-hover

Publishing Checklist

Before publishing, ensure:

• All tests pass
• Code is linted and formatted
• TypeScript compilation succeeds
• Example builds and runs correctly
• README is up to date
• Package.json has correct metadata (name, version, author, repository)
• License file is present
• No sensitive information in the package
• Version number is appropriate for the changes

Troubleshooting

Package name already taken

If the package name is already taken, update the name field in package.json to something unique.

Publishing fails

• Ensure you're logged in: npm whoami
• Check if you have permission to publish: npm access ls-packages
• Verify the package name is available

Build errors

• Check that all dependencies are installed: npm install
• Ensure TypeScript configuration is correct
• Verify Rollup configuration is valid

License

MIT © [Your Name]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.