Buttons Panel

approved

by Kevin

Create customizable button panels for quick access to files, commands, links, and scripts. - This plugin has not been manually reviewed by Obsidian staff.

4 stars1,436 downloadsUpdated 6d agoMIT

Buttons Panel

Obsidian Downloads GitHub Downloads

[中文 | English | Русский]

Buttons Panel is a modern Obsidian plugin that lets you create a customizable button panel for quick access to files, commands, links, and scripts.

✨ 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:

ModeIconBehavior
🔒 LockedlockView only — all interactions disabled (no drag, no context menu)
↕️ Sortarrow-up-downLong-press drag to reorder buttons and categories
✏️ EditpencilContext 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.

FeatureDescription
Open/CloseClick a tile to expand; click outside, press ESC, or click blank space (configurable) to close
PinClick 📌 to lock — folder stays open until unpinned or you switch folders
Edit nameClick folder name to rename (configurable in settings)
Reorder foldersLong-press drag in sort mode
Cross-folder dragDrag button out → auto-close → hover 0.6s on another tile → auto-expand → continue sorting
Auto-scrollDrag 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):

TargetList viewTabbed viewFolder view
ButtonsLong-press a button, then drag to reorder within a category; drag over another category's tab/zone to move across categoriesSame; active tab's grid supports drag reorderDrag within expanded folder or between folders; hover 0.6s over a tile to auto-expand
CategoriesLong-press the category block (title or non-button area), then drag vertically to reorderLong-press a tab, hold ~0.4s over another tab to confirm drop target, then release to reorderLong-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:

🙏 Acknowledgements

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

For plugin developers

Search results and similarity scores are powered by semantic analysis of your plugin's README. If your plugin isn't appearing for searches you'd expect, try updating your README to clearly describe your plugin's purpose, features, and use cases.