{"id":35149130,"url":"https://github.com/yanganto/ratatui-keybind-template","last_synced_at":"2026-05-21T19:35:36.323Z","repository":{"id":328909661,"uuid":"1116093296","full_name":"yanganto/ratatui-keybind-template","owner":"yanganto","description":"A template to avoid keybinding issues when your TUI go big","archived":false,"fork":false,"pushed_at":"2026-04-09T15:02:30.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-09T17:04:54.451Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yanganto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-14T07:17:14.000Z","updated_at":"2026-04-09T15:03:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yanganto/ratatui-keybind-template","commit_stats":null,"previous_names":["yanganto/ratatui-keybind-template"],"tags_count":2,"template":true,"template_full_name":null,"purl":"pkg:github/yanganto/ratatui-keybind-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanganto%2Fratatui-keybind-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanganto%2Fratatui-keybind-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanganto%2Fratatui-keybind-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanganto%2Fratatui-keybind-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yanganto","download_url":"https://codeload.github.com/yanganto/ratatui-keybind-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanganto%2Fratatui-keybind-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33311888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"ssl_error","status_checked_at":"2026-05-21T12:22:11.673Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-28T14:53:28.562Z","updated_at":"2026-05-21T19:35:36.318Z","avatar_url":"https://github.com/yanganto.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ratatui-keybind-template\nThis is a [Ratatui](https://github.com/ratatui/ratatui) template that provides a modular keybinding system using the [crossterm-keybind](https://github.com/yanganto/crossterm-keybind) crate for building terminal user interfaces. It demonstrates best practices for handling keybindings in a scalable way, making it easy to manage keybindings as your application grows.  \nCurrent template is for ratatui v0.30.0, you may check on [release tags](https://github.com/yanganto/ratatui-keybind-template/releases) for the templates with different versions of ratatui.\n\n## Features\n\n- **crossterm-keybind Integration**: Uses the crossterm-keybind crate for powerful keybinding management\n- **Configurable Keybindings**: Users can customize keybindings via TOML configuration files\n- **Backward Compatible**: Legacy key configs still work with new release if there are only additions in keybind enum.\n- **Multiple Keybindings per Action**: Support for assigning multiple key combinations to a single action\n- **Auto-generated Config**: Generate example configuration files with `KeyEvent::to_toml_example()`\n- **Clean Syntax**: Define keybindings with derive macros using simple string notation\n- **Extensible Design**: Easy to add new keybindings and actions\n\n## Using This Template\n\nClick the \"Use this template\" button on GitHub to create a new repository based on this template. Then clone your new repository and start building your TUI application.\n\n```bash\ngit clone https://github.com/YOUR_USERNAME/YOUR_NEW_REPO.git\ncd YOUR_NEW_REPO\ncargo run\n```\n\n## Quick Start\n\nRun the example application:\n\n```bash\ncargo run\n```\n\n### Keybindings\n\n**Default Keybindings:**\n- `q` - Quit the application\n- `Q` - Quit the application\n- `Ctrl+c` - Quit the application\n\nYou can customize these by generating a config file (see Configuration section below).\n\n## Project Structure\n\n```\nsrc/\n├── main.rs       # Application entry point and terminal setup\n├── app.rs        # Application state and logic\n├── keybinds.rs   # Keybinding definitions using crossterm-keybind\n└── ui.rs         # UI rendering logic\n```\n\n## Architecture\n\n### Keybinding System with crossterm-keybind\n\nThe keybinding system uses the `crossterm-keybind` crate, which provides:\n\n1. **KeyEvent Enum**: Define keybindings using derive macros\n2. **Multiple Bindings**: Assign multiple key combinations to one action\n3. **Config Files**: Load custom keybindings from TOML files\n4. **Display Helpers**: Auto-generate help text for keybindings\n\n### Adding New Keybindings\n\nTo add a new keybinding event:\n\n1. Add a new variant to the `KeyEvent` enum in `src/keybinds.rs`\n2. Use the `#[keybindings[...]]` attribute to define key combinations\n3. Handle the event in `App::handle_key()` in `src/app.rs`\n\nExample:\n\n```rust\n// 1. Add to KeyEvent enum in src/keybinds.rs\nuse crossterm_keybind::KeyBind;\n\n#[derive(KeyBind)]\npub enum KeyEvent {\n    /// Quit the application\n    #[keybindings[\"Control+c\", \"Q\", \"q\"]]\n    Quit,\n    \n    /// Your new action - press 'h' or 'F1' to trigger\n    #[keybindings[\"h\", \"F1\"]]\n    ShowHelp,\n}\n\n// 2. Handle in src/app.rs\nimpl App {\n    pub fn handle_key(\u0026mut self, key: crossterm::event::KeyEvent) -\u003e bool {\n        // Option 1: match_any\n        if KeyBindEvent::Quit.match_any(\u0026key) {\n            return false;\n        }\n        if KeyBindEvent::ShowHelp.match_any(\u0026key) {\n            // Show help logic\n        }\n\n        // Option 2 match events from dispatch method\n        for event in KeyBindEvent::dispatch(\u0026key) {\n            match event {\n                KeyBindEvent::Quit =\u003e return false,\n                KeyBindEvent::ShowHelp =\u003e {\n                  // Show help logic\n                }\n            }\n        }\n        true\n    }\n}\n```\n\n### Configuration\n\nGenerate a default configuration file:\n\n```rust\nuse crossterm_keybind::KeyBindTrait;\nuse crate::keybinds::KeyEvent;\n\n// Generate example config\nKeyEvent::to_toml_example(\"keybinds.toml\").unwrap();\n```\n\nThis creates a `keybinds.toml` file:\n\n```toml\n# Quit the application\nquit = [\"Control+c\", \"Q\", \"q\"]\n\n# Show help\nshow_help = [\"h\", \"F1\"]\n```\n\nUsers can then customize the keybindings and load them:\n\n```rust\n// In main.rs\nKeyEvent::init_and_load(Some(\"keybinds.toml\".into()))?;\n```\n\n## Dependencies\n\n- [ratatui](https://github.com/ratatui/ratatui) - Terminal UI library\n- [crossterm](https://github.com/crossterm-rs/crossterm) - Terminal manipulation library\n- [crossterm-keybind](https://github.com/yanganto/crossterm-keybind) - Keybinding management with config support\n- [color-eyre](https://github.com/eyre-rs/color-eyre) - Error handling\n- [serde](https://github.com/serde-rs/serde) - Serialization framework (required by crossterm-keybind)\n\n## Testing\n\nRun tests with:\n\n```bash\ncargo test\n```\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details\n\n## Contributing\n\nContributions are welcome! Feel free to open issues or submit pull requests.\n\n## Acknowledgments\n\nThis template is inspired by the [ratatui templates](https://github.com/ratatui/templates) project and follows best practices from the Ratatui community.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyanganto%2Fratatui-keybind-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyanganto%2Fratatui-keybind-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyanganto%2Fratatui-keybind-template/lists"}