---
slug: "freshbooks-speed"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/jaredlander/freshbooks-speed@main/README.md"
repo: "https://github.com/jaredlander/freshbooks-speed"
source_file: "README.md"
branch: "main"
---
# FreshBooks Speed Boost

**A Chrome extension that supercharges FreshBooks dropdowns for blazing-fast data entry.**

## The Problem

If you use FreshBooks with hundreds of merchants or categories, you know the pain:

- Opening dropdowns can take **2-5 seconds** to render
- Pages freeze while loading hundreds of items
- Data entry becomes frustratingly slow
- Your productivity suffers

FreshBooks renders all dropdown items at once, causing performance issues when you have large datasets.

## The Solution

FreshBooks Speed Boost adds **client-side pagination** to dropdowns, showing only 50 items at a time:

- Dropdowns open in **under 200ms** (10-25x faster)
- Smooth, responsive interface
- No more freezing or waiting
- Your search/filter functionality still works perfectly

### Performance Improvement

| Scenario | Before | After |
|----------|--------|-------|
| 500 merchants | 3-5 seconds | <200ms |
| 1000 categories | 5+ seconds | <200ms |
| Memory usage | Increases over time | Stable |

## Features

✅ **Automatic pagination** - Dropdowns with >50 items get paginated automatically
✅ **Next/Previous navigation** - Easy-to-use pagination controls
✅ **Page indicator** - Always know where you are (e.g., "Page 1 of 10")
✅ **Search/filter compatible** - Type to filter, pagination hides automatically
✅ **Memory efficient** - Proper cleanup prevents memory leaks
✅ **Works with all dropdowns** - Merchant, category, and any other FreshBooks dropdown
✅ **No dependencies** - Lightweight, vanilla JavaScript

## Installation

### Option A: Manual Installation (Recommended for Now)

1. **Download the extension files** from this repository

2. **Open Chrome Extensions**
   - Navigate to `chrome://extensions/`
   - Or click the puzzle icon → "Manage Extensions"

3. **Enable Developer Mode**
   - Toggle the "Developer mode" switch in the top right corner

4. **Load the extension**
   - Click "Load unpacked"
   - Select the `freshbooks-speed-boost` directory
   - The extension icon should appear in your toolbar

5. **Done!** - The extension is now active on all FreshBooks pages

### Option B: Chrome Web Store

*Chrome Web Store listing coming soon*

## Usage

Using the extension is automatic once installed:

1. **Navigate to FreshBooks** (https://my.freshbooks.com/)

2. **Open any dropdown** (merchant, category, etc.)

3. **Pagination appears automatically** if there are more than 50 items:
   ```
   [← Previous]  Page 1 of 10 (500 total)  [Next →]
   ```

4. **Click Next/Previous** to navigate between pages

5. **Type to filter** - Pagination disappears, showing all matching results

6. **Close dropdown** - Memory is automatically cleaned up

### Example Scenarios

**Scenario 1: Browsing merchants**
- Open merchant dropdown
- See first 50 merchants
- Click "Next" to see merchants 51-100
- Continue browsing with fast, responsive UI

**Scenario 2: Searching for a specific merchant**
- Open merchant dropdown
- Type "Acme" to filter
- Pagination disappears, all "Acme" merchants shown
- Clear search, pagination returns

**Scenario 3: Working with categories**
- Works identically with category dropdowns
- Or any other FreshBooks dropdown with many items

## Technical Details

- **Platform:** Chrome Extension (Manifest V3)
- **Compatibility:** Chrome, Edge, Brave, and other Chromium-based browsers
- **Technology:** Vanilla JavaScript (no dependencies)
- **Injection:** Content script runs on https://my.freshbooks.com/*
- **Selectors:** Uses semantic HTML attributes (`role="listbox"`, etc.) for stability
- **Memory Management:** Proper cleanup prevents memory leaks
- **Page Size:** 50 items per page (configurable in source)

### How It Works

1. Extension monitors for FreshBooks dropdowns using MutationObserver
2. When a dropdown with >50 items opens, pagination is applied
3. DOM elements outside the current page are hidden (not removed)
4. User interactions (Next/Previous) show/hide appropriate items
5. When dropdown closes, all references are cleaned up to prevent memory leaks

## Requirements

- **Browser:** Chrome, Edge, Brave, or any Chromium-based browser
- **FreshBooks Account:** Active account with access to https://my.freshbooks.com/*
- **Permissions:** Extension only accesses FreshBooks pages (see manifest.json)

## Troubleshooting

### Extension not working?

1. **Check if enabled:** Go to `chrome://extensions/` and ensure the extension is enabled
2. **Reload FreshBooks:** Refresh your FreshBooks page after installing
3. **Check console:** Open DevTools (F12) → Console, look for "[FreshBooks Speed Boost]" messages
4. **Verify page URL:** Extension only works on https://my.freshbooks.com/* pages

### Pagination not appearing?

- **Check item count:** Pagination only appears for dropdowns with >50 items
- **Disable filter:** If you're filtering, pagination hides automatically (this is expected)
- **Ember selectors changed:** FreshBooks may have updated their UI. Check CLAUDE.md for selector updates

### Performance issues?

- The extension should improve performance. If you experience issues:
  - Disable other extensions to rule out conflicts
  - Clear browser cache and reload
  - Check Chrome DevTools Memory profiler for memory leaks (shouldn't happen with v1.1+)

## Version History

### v1.1 (Current)
- Fixed memory leaks (DOM element references, event listeners)
- Extended support to all FreshBooks dropdowns (not just merchants)
- Improved filtering detection for all dropdown types
- Added proper cleanup when dropdowns close
- Event delegation for better performance

### v1.0 (Initial Release)
- Initial release with merchant dropdown pagination
- Basic pagination controls (Next/Previous)
- Page indicator
- Search/filter compatibility

## Contributing

Contributions are welcome! Here's how you can help:

### Reporting Issues

Found a bug or have a feature request? Please open an issue with:
- Browser version
- Steps to reproduce
- Expected vs actual behavior
- Console errors (if any)

### Development Setup

1. Clone this repository
2. Load extension in Chrome (see Installation)
3. Make changes to `content.js`
4. Reload extension at `chrome://extensions/`
5. Test on FreshBooks

### Code Guidelines

- Follow existing code style (vanilla JS, ES6+)
- Add comments for complex logic
- Test with varying dropdown sizes (10, 50, 100, 500+ items)
- Ensure memory cleanup works (check with Chrome DevTools)
- See CLAUDE.md for development guidelines

## License

MIT License - see [LICENSE](https://github.com/jaredlander/freshbooks-speed/tree/HEAD/LICENSE) file for details

Copyright (c) 2026 Jared P. Lander

## Disclaimer

This extension is provided "as is" without warranty. It is not affiliated with, endorsed by, or officially connected with FreshBooks Inc. Use at your own risk.

---

**Built with ❤️ for the FreshBooks community**

*Having issues or questions? Open an issue on GitHub or check the Troubleshooting section above.*