react-material-bottom-sheet

React Material Bottom Sheet

A modern, accessible React component library for Material Design bottom sheets with smooth drag gestures, snap points, and TypeScript support.

Watch the demo to see the drag and snap behavior in action.

✨ Features

• 🎨 Material Design Compliant: Follows Android Material Design 3 guidelines
• 👆 Touch & Drag Support: Smooth drag-to-close and fling gestures
• 📏 Configurable Snap Points: Multiple snap positions with customizable heights
• ♿ Accessibility First: Full keyboard navigation and screen reader support
• 🔷 TypeScript Ready: Complete type definitions included
• 🎯 Zero Dependencies: Lightweight with no external dependencies
• 📱 Mobile Optimized: Touch-friendly interactions and responsive design
• 🎭 Customizable Styling: Easy theming and CSS customization

🚀 Installation

npm install react-material-bottom-sheet

Peer Dependencies

This library requires React 18+ and React DOM 18+:

npm install react@^18.0.0 react-dom@^18.0.0

Note: The library is compatible with both React 18 and React 19.

📖 Quick Start

import React, { useState } from 'react';
import { BottomSheet } from 'react-material-bottom-sheet';
import 'react-material-bottom-sheet/style.css';

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>
        Open Bottom Sheet
      </button>

      <BottomSheet
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      >
        <div style={{ padding: '20px' }}>
          <h2>Bottom Sheet Content</h2>
          <p>This is the content of the bottom sheet.</p>
          <button onClick={() => setIsOpen(false)}>Close</button>
        </div>
      </BottomSheet>
    </div>
  );
}

🎯 Advanced Usage

Custom Snap Points

import { BottomSheet } from 'react-material-bottom-sheet';

function CustomSnaps() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <BottomSheet
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
      snapPoints={[0.2, 0.5, 0.9]} // 20%, 50%, 90% of screen height
      initialSnap={1} // Start at 50% height
    >
      <div style={{ padding: '20px' }}>
        <h3>Custom Snap Points</h3>
        <p>Drag me to different heights!</p>
      </div>
    </BottomSheet>
  );
}

With Form Content

function FormSheet() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <BottomSheet isOpen={isOpen} onClose={() => setIsOpen(false)}>
      <div style={{ padding: '20px' }}>
        <h3>Contact Form</h3>
        <form onSubmit={(e) => {
          e.preventDefault();
          // Handle form submission
          setIsOpen(false);
        }}>
          <input type="text" placeholder="Name" required />
          <input type="email" placeholder="Email" required />
          <textarea placeholder="Message" rows={4} />
          <button type="submit">Send</button>
        </form>
      </div>
    </BottomSheet>
  );
}

📚 API Reference

BottomSheet Props

Prop	Type	Default	Description
isOpen	boolean	-	Required. Controls bottom sheet visibility
onClose	() => void	-	Required. Called when user closes the sheet
children	React.ReactNode	-	Required. Content to display inside the sheet
snapPoints	number[]	[0.3, 0.8]	Array of snap points as screen height fractions (0-1)
initialSnap	number	0	Index of initial snap point to show
closeOnDragDown	boolean	true	Allow closing by dragging down from top snap
closeThreshold	number	0.3	Drag distance threshold for close (as fraction)
velocityThreshold	number	0.3	Velocity threshold for fling gestures (pixels/ms)

TypeScript Support

import type { BottomSheetProps } from 'react-material-bottom-sheet';

const customProps: BottomSheetProps = {
  isOpen: true,
  onClose: () => console.log('Closed'),
  snapPoints: [0.25, 0.5, 0.75],
  initialSnap: 1,
  children: <div>Content</div>
};

🎨 Styling & Theming

The component uses CSS custom properties for easy theming:

/* Override default styles */
:root {
  --bottom-sheet-background: #ffffff;
  --bottom-sheet-border-radius: 16px;
  --bottom-sheet-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
  --bottom-sheet-handle-color: #e0e0e0;
}

Custom CSS Classes

<BottomSheet
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  className="my-custom-sheet"
>
  {/* Your content */}
</BottomSheet>

.my-custom-sheet {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

🧪 Testing

Unit Tests

npm test

End-to-End Tests

npm run test:e2e

📁 Project Structure

react-material-bottom-sheet/
├── src/
│   ├── BottomSheet.tsx      # Main component
│   ├── BottomSheet.css      # Styles
│   ├── index.ts            # Exports
│   └── __tests__/          # Unit tests
├── example/                # Demo application
├── docs/                   # Documentation site
├── dist/                   # Built library
└── tests/                  # E2E tests

🛠️ Development

Setup

# Clone the repository
git clone https://github.com/sitharaj88/react-material-bottom-sheet.git
cd react-material-bottom-sheet

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

Building the Library

npm run build

This creates optimized bundles in the dist/ directory.

Running the Example

cd example
npm install
npm run dev

Visit http://localhost:5173 to see the demo.

📖 Documentation

For comprehensive documentation, API reference, and more examples, visit our documentation site.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

• Fork the repository
• Create a feature branch: git checkout -b feature/amazing-feature
• Make your changes and add tests
• Run the test suite: npm test
• Submit a pull request

Code Style

This project uses ESLint for code linting. Please run:

npm run lint

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by Material Design 3 guidelines
• Built with modern React patterns and TypeScript
• Thanks to the React community for excellent tooling

📞 Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

Made with ❤️ by sitharaj88