✨ Features

• 🎯 Quick Access: Instantly open files, execute commands, visit links, or run scripts with a single click.
• 🎨 Icon Picker: Integrated Lucide icon library with search and live preview.
• 🏷️ Three View Modes: Switch between list, tabbed, and folder views.
• 📁 Folder View: Android-style folder grid with drag-and-drop, auto-expand on hover, pin to keep open, click-to-close, and editable folder names.
• 📁 Category Management: Organize buttons by category; reorder categories and buttons via long-press drag-and-drop.
• ⚙️ Flexible Configuration: Fully customizable panel layout, button styles, and animation effects.
• 📱 Responsive Design: Optimized for both desktop and mobile devices.
• 🌙 Theme Adaptation: Seamlessly adapts to Obsidian’s light and dark themes.
• 🎛️ Dedicated Settings Tab: Manage all plugin settings in a separate, user-friendly tab.
• 🔄 Live Updates: All changes take effect immediately—no restart required.
• 🛡️ Form Validation: Required fields (button name, file path, command ID, URL, folder, script name) are highlighted in red if empty for intuitive feedback.
• 🖱️ Interaction Mode: Three modes — Locked (view only), Sort (drag to reorder), Edit (create/edit/delete via context menu) — switchable from the top navigation bar.
• 🧭 Top Navigation Bar: Dropdown menus to quickly switch panel view, button style, and interaction mode; plus search and settings access.
• 🔍 Search Feature: The navigation bar includes a search function that filters categories and buttons in real-time for quick access.
• 🔗 Action Sequences: Configure multiple actions for a single button and execute them in order with one click.

🚀 Installation

🏪 Install from Community Plugins (Recommended)

1. Open Obsidian and go to Settings → Community Plugins.
2. Click Browse and search for "Buttons Panel".
3. Click Install, then Enable.

📦 Manual Installation

1. Download the latest release from the Releases page.
2. Place the plugin folder into your Obsidian plugins directory (usually .obsidian/plugins/, e.g. YourVault/.obsidian/plugins/buttons-panel/).
3. Enable the plugin in Obsidian under Settings → Community Plugins.

🔧 Install via BRAT (Recommended for Beta Users)

1. Install the BRAT plugin.
2. In BRAT settings, click "Add Beta plugin".
3. Enter TracingOrigins/obsidian-buttons-panel-plugin.
4. Enable the plugin.

📖 Usage

🎯 Opening the Button Panel

• Use the command palette (Ctrl+P) and run "Open buttons panel (right sidebar)".
• Click the grid icon in the left ribbon to quickly open the panel and settings.
• The button panel will appear in the right sidebar for fast access.

⚙️ Opening the Button Panel Settings

• Use the command palette to run "Open buttons panel settings (central content area)".
• The settings page will open in the main content area for detailed configuration.
• You can also access settings via the plugin section in Obsidian’s settings.

🔗 Action Sequences

• Action Sequences: Configure a button to perform multiple actions in sequence (e.g., create a file, insert a template, run a script). Clicking the button will execute all actions in order. Each action can be of a different type, greatly enhancing automation and batch processing.
  • How to configure: In the button editor, click "Add Action" to add multiple actions and drag to reorder them.
  • Typical use cases: One-click to create and open a template note, batch execute multiple commands, automate daily routines, and more.

🔗 Supported Action Types

• Open File: Open any file in your vault.
• Command: Execute any Obsidian command.
• Open Link: Open an external web link.
• Create File: Create a new file at a specified location, supporting date variables (e.g. {{DATE:YYYY-MM-DD}}) and templates.
• Run Script: Run a custom JS script from your vault (supports both QuickAdd and Components script formats). Scripts must be placed in the configured script folder.

✅ Form Validation

• When creating or editing a button, clicking "Save" will automatically validate all required fields.
• If any required field is empty, the corresponding input will be highlighted in red.
• The red highlight disappears automatically once the field is filled.

🎛️ Panel Options

• View Mode: Choose between list, tabbed, or folder view.
• Button Style: Display icon and text on the same line, or icon above text (folder view always uses icon-top).
• Animation: Enable button hover animation.
• Interaction Mode: Choose between Locked (view only), Sort (drag to reorder), or Edit (create/edit/delete).
• Top Navigation: Enable or disable the top navigation bar.

Example: Choose "Tabbed View" to group buttons by category.

📁 Path Management

• Template Folder Path: Set the folder path for storing template files (e.g., templates/). The create file action will use templates from this path.
• Script Folder Path: Set the folder path for storing script files (e.g., scripts/). The run script action will load script files from this path.
• Path Validation: Paths are validated in real-time. Invalid paths are highlighted with a red border.
• One-Click Creation: Click the "Create Paths" button to automatically create any missing folders.

Example: Set the template folder to templates/ and script folder to scripts/ so that the create file and run script features work properly.

🖱️ Interaction Mode

The navigation bar edit button opens a dropdown with three modes:

Mode	Icon	Behavior
🔒 Locked	lock	View only — all interactions disabled (no drag, no context menu)
↕️ Sort	arrow-up-down	Long-press drag to reorder buttons and categories
✏️ Edit	pencil	Context menu (right-click / long-press) to add, edit, copy, or delete

• Switch modes from the top navigation bar dropdown or in Panel Options settings.
• Drag-and-drop reordering is only available in Sort mode.
• Editing controls and context menus are only available in Edit mode.

� Folder View

Switch to folder view from the navigation bar or settings. Categories appear as folder tiles in a responsive grid.

Feature	Description
Open/Close	Click a tile to expand; click outside, press ESC, or click blank space (configurable) to close
Pin	Click 📌 to lock — folder stays open until unpinned or you switch folders
Edit name	Click folder name to rename (configurable in settings)
Reorder folders	Long-press drag in sort mode
Cross-folder drag	Drag button out → auto-close → hover 0.6s on another tile → auto-expand → continue sorting
Auto-scroll	Drag near edges inside expanded folder to scroll

Folder settings: folder name editable, show button count, close on blank click.

�🔀 Drag-and-Drop Reordering

When Sort mode is active and search is not active, long-press and drag to reorder (mouse long-press works on desktop too):

Target	List view	Tabbed view	Folder view
Buttons	Long-press a button, then drag to reorder within a category; drag over another category's tab/zone to move across categories	Same; active tab's grid supports drag reorder	Drag within expanded folder or between folders; hover 0.6s over a tile to auto-expand
Categories	Long-press the category block (title or non-button area), then drag vertically to reorder	Long-press a tab, hold ~0.4s over another tab to confirm drop target, then release to reorder	Long-press a tile to reorder in grid

• Order is saved automatically when you release.
• Reordering is unavailable in Locked or Edit mode, or while search is active.

📱 Touch Gestures (Mobile)

• Scroll the panel: Swipe up/down on the panel (list view) or left/right on the tab bar (tabbed view) without long-pressing.
• Drag to reorder: Long-press (~0.5s) on a button or category/tab, then drag. While dragging, panel scrolling is locked so the item follows your finger.
• If a quick swipe is detected before the long-press completes, the gesture is treated as scrolling and drag does not start.

🧭 Top Navigation Bar

• The panel features a top navigation bar with the following functions:
  • Panel View Switch: Switch between tabbed and list views.
  • Button Style Switch: Instantly change button styles.
  • Interaction Mode: Switch between Locked, Sort, and Edit modes via dropdown.
  • Search Feature: Click the search icon to open the search box and filter categories and button names in real-time.
  • Panel Settings: Open the panel settings page with one click.
• Tab bar scrolling (tabbed view, many tabs): On mobile, swipe left/right on the tab bar; on desktop, hover the tab bar, hold Shift, and scroll the mouse wheel horizontally.
• The navigation bar is designed for efficiency and a smooth user experience.

🔍 Search Feature

• Click the search icon in the navigation bar to open the search box.
• After entering keywords, the panel will automatically filter and display matching categories and buttons.
• Search only filters category names and button names, with real-time updates.
• Click the clear button or close the search box to clear the search criteria.

🧩 Script Feature

• In the button editor, select "Script" as the action type and choose or enter a script file name (.js only).

• Script files must be placed in the script folder specified in plugin settings (e.g., scripts/). You can customize this path in the settings tab.

• Two script formats are supported:

  • QuickAdd script format: The script must export an async function, for example:

    // scripts/hello.js
    module.exports = async function (params, app, plugin, notice) {
        notice('Hello from script!');
        // You can access the Obsidian API, plugin instance, etc. here
    };
    

  • Components script format: The script must export an object whose default.entry is an async function, for example:

    // scripts/components-demo.js
    exports.default = {
        entry: async function (params, app, plugin, notice) {
            notice('Hello from Components script!');
            // You can access the Obsidian API, plugin instance, etc. here
        },
    };
    

• The script environment injects app (Obsidian instance), plugin (plugin instance), and notice (notification method).

• Script errors are automatically caught and shown as notifications.

• Security Note: Do not run scripts from untrusted sources. Script execution has inherent risks.

Example: Write batch processing or automation scripts and run them with a single click.
Example: Configure a button with “Create File → Insert Template → Run Script” actions, and all will be executed in order with one click.

🛠️ Development

• Clone this repository.
• Make sure your NodeJS is at least v18 (node --version), LTS version recommended.
• Run npm install to install dependencies.
• Run npm run dev to start development mode with live compilation (automatically deploys to test vault).
• Run npm run build to build the production version and deploy to test vault.
• Run npm run lint to check code quality.
• To deploy to a custom vault, create a .env file in the project root and add: VAULT_PATH=/path/to/your/vault.

🎨 Tech Stack

• TypeScript: Type-safe JavaScript with strict mode.
• React: Modern framework for building user interfaces.
• Obsidian API: Official plugin API.
• Lucide Icons: Modern icon library (6000+ icons).
• CSS Grid & Flexbox: Responsive layout.
• ESBuild: Fast build tool with TypeScript and React support.
• @dnd-kit: Drag-and-drop for button and category reordering.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🌟 Support & Help

If you find this plugin helpful, please consider:

• ⭐ Starring the repository.
• 🐛 Using the bug report template to submit bug reports.
• 💡 Using the feature request template to submit feature suggestions.
• ❓ Asking questions or sharing ideas in our Discussions.
• 📝 Referring to the Contributing Guide to contribute code or documentation.
• 💰 Providing sponsorship to the developer (if available).

🙏 Acknowledgements

This plugin uses icons from the open-source project Lucide, which is licensed under the ISC License.