Skip to content

USAGE.md

Latest commit

 

History

History
307 lines (239 loc) · 6.69 KB

USAGE.md

File metadata and controls

307 lines (239 loc) · 6.69 KB

Back2Top Usage Guide

Overview

Back2Top is a beautiful, customizable scroll-to-top button component for React applications. This guide explains how to use the packaged files and integrate the component into your project.

Package Contents

After building the package (npm run build in the lib directory), you'll find the following files in lib/dist/:

JavaScript Files

  • index.js - CommonJS build for Node.js environments
  • index.esm.js - ES Module build for modern bundlers
  • index.umd.js - Universal Module Definition for browsers
  • index.umd.min.js - Minified UMD build for production

TypeScript Declaration Files

  • types/index.d.ts - TypeScript type definitions
  • types/ directory - Complete type definitions for all components

Installation Methods

Method 1: NPM Package (Recommended)

npm install back2topfun
# or
yarn add back2topfun

Method 2: Direct File Usage

Download the built files and include them in your project:

<!-- For browser usage -->
<script src="path/to/index.umd.min.js"></script>

<!-- For ES modules -->
<script type="module">
  import { Back2Top } from './path/to/index.esm.js';
</script>

Usage Examples

React Application (ES Modules)

import React from 'react';
import { Back2Top } from 'back2topfun';

function App() {
  return (
    <div>
      {/* Your app content */}
      <Back2Top 
        animation="fade"
        position="bottom-right"
        showAt={300}
        smooth={true}
      />
    </div>
  );
}

export default App;

Browser Usage (UMD)

<!DOCTYPE html>
<html>
<head>
  <title>Back2Top Example</title>
  <!-- React dependencies -->
  <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
  <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
  
  <!-- Back2Top -->
  <script src="./lib/dist/index.umd.min.js"></script>
</head>
<body>
  <div id="root"></div>
  
  <script>
    const { Back2Top } = window.Back2Top;
    
    function App() {
      return React.createElement(Back2Top, {
        animation: 'slide',
        position: 'bottom-right',
        showAt: 200
      });
    }
    
    ReactDOM.render(React.createElement(App), document.getElementById('root'));
  </script>
</body>
</html>

Next.js Application

import dynamic from 'next/dynamic';

// Dynamic import to avoid SSR issues
const Back2Top = dynamic(
  () => import('back2topfun').then(mod => mod.Back2Top),
  { ssr: false }
);

export default function Layout({ children }) {
  return (
    <div>
      {children}
      <Back2Top 
        animation="bounce"
        position="bottom-right"
        showAt={400}
      />
    </div>
  );
}

Configuration Options

Basic Props

interface Back2TopProps {
  // Animation type
  animation?: 'fade' | 'slide' | 'bounce' | 'zoom' | 'rotate';
  
  // Position on screen
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  
  // Show button after scrolling X pixels
  showAt?: number;
  
  // Smooth scrolling behavior
  smooth?: boolean;
  
  // Custom styling
  className?: string;
  style?: React.CSSProperties;
  
  // Button size
  size?: 'small' | 'medium' | 'large';
  
  // Color theme
  theme?: 'light' | 'dark' | 'primary' | 'custom';
  
  // Custom colors (when theme is 'custom')
  colors?: {
    background?: string;
    foreground?: string;
    hover?: string;
  };
}

Advanced Configuration

<Back2Top
  animation="slide"
  position="bottom-right"
  showAt={300}
  smooth={true}
  size="medium"
  theme="custom"
  colors={{
    background: '#3b82f6',
    foreground: '#ffffff',
    hover: '#2563eb'
  }}
  className="my-scroll-button"
  style={{ zIndex: 1000 }}
/>

Technology Stack

JavaScript-Based Features

  • Animations: Powered by Framer Motion for smooth, performant animations
  • Scroll Detection: JavaScript-based scroll position monitoring
  • Smooth Scrolling: Uses window.scrollTo() with smooth behavior
  • Event Handling: Click and keyboard event management

CSS3 Alternative

While the component uses JavaScript for enhanced features, basic scroll-to-top functionality can be achieved with pure CSS3:

/* CSS-only scroll-to-top (limited functionality) */
.scroll-to-top {
  position: fixed;
  bottom: 20px;
  right: 20px;
  width: 50px;
  height: 50px;
  background: #3b82f6;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  cursor: pointer;
  transition: all 0.3s ease;
  opacity: 0;
  visibility: hidden;
}

.scroll-to-top.visible {
  opacity: 1;
  visibility: visible;
}

.scroll-to-top:hover {
  background: #2563eb;
  transform: translateY(-2px);
}

However, JavaScript is required for:

  • Scroll position detection
  • Smooth scrolling behavior
  • Advanced animations
  • Dynamic show/hide logic
  • Accessibility features

Dependencies

Required Dependencies

  • React (^16.8.0 || ^17.0.0 || ^18.0.0)
  • React DOM (^16.8.0 || ^17.0.0 || ^18.0.0)

Optional Dependencies

  • Framer Motion (^10.0.0) - For advanced animations
  • Lucide React (^0.263.0) - For icons

Browser Support

  • Modern Browsers: Chrome 60+, Firefox 60+, Safari 12+, Edge 79+
  • Mobile: iOS Safari 12+, Chrome Mobile 60+
  • IE Support: Not supported (requires modern JavaScript features)

Performance Considerations

  1. Bundle Size:

    • UMD minified: ~15KB gzipped
    • ES Module: ~12KB gzipped
    • Tree-shakable when using ES modules

  2. Runtime Performance:

    • Optimized scroll event handling with throttling
    • Efficient animation using Framer Motion
    • Minimal DOM manipulation

  3. Loading Strategy:

    • Use dynamic imports for code splitting
    • Consider lazy loading for non-critical usage

Troubleshooting

Common Issues

  1. Component not showing:

    • Check if scroll position exceeds showAt value
    • Verify React and ReactDOM are loaded
    • Check console for JavaScript errors

  2. Animations not working:

    • Ensure Framer Motion is installed
    • Check for CSS conflicts
    • Verify browser supports CSS transforms

  3. TypeScript errors:

    • Install type definitions: npm install @types/react
    • Check TypeScript version compatibility

Debug Mode

Enable debug logging:

<Back2Top 
  debug={true}
  // ... other props
/>

Examples Repository

Find more examples and demos at:

Support

For issues and questions: