{"id":20003672,"url":"https://github.com/drsmile444/telegraf-menu","last_synced_at":"2025-06-19T01:33:38.582Z","repository":{"id":43217636,"uuid":"379043796","full_name":"DrSmile444/telegraf-menu","owner":"DrSmile444","description":"📋 State-based Telegraf menus (Radio, Checkbox, Range) written with TypeScript","archived":false,"fork":false,"pushed_at":"2022-03-12T20:30:13.000Z","size":3557,"stargazers_count":25,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-17T08:43:46.070Z","etag":null,"topics":["checkbox","menu","radio","range","telegraf","telegraf-menu"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/DrSmile444.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-06-21T19:38:45.000Z","updated_at":"2024-10-29T00:59:44.000Z","dependencies_parsed_at":"2022-09-06T05:41:50.699Z","dependency_job_id":null,"html_url":"https://github.com/DrSmile444/telegraf-menu","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DrSmile444/telegraf-menu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrSmile444%2Ftelegraf-menu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrSmile444%2Ftelegraf-menu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrSmile444%2Ftelegraf-menu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrSmile444%2Ftelegraf-menu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DrSmile444","download_url":"https://codeload.github.com/DrSmile444/telegraf-menu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DrSmile444%2Ftelegraf-menu/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260663336,"owners_count":23044097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["checkbox","menu","radio","range","telegraf","telegraf-menu"],"created_at":"2024-11-13T05:26:41.034Z","updated_at":"2025-06-19T01:33:33.567Z","avatar_url":"https://github.com/DrSmile444.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# telegraf-menu 📋\n\nState-based Telegraf menus (Radio, Checkbox, Range) written with TypeScript.\n\n```bash\n$ npm install telegraf-menu\n```\n\n![example](https://github.com/DrSmile444/telegraf-menu/raw/main/docs/telegraf-menu.main.gif)\n## Table of Contents\n\n\n- [Philosophy](#philosophy)\n- [Features](#features)\n- [Installing](#installing)\n- [Menu Types](#menu-types)\n  - [Regular Menu](#regular-menu)\n  - [Checkbox Menu](#checkbox-menu)\n  - [Radio Menu](#radio-menu)\n  - [Range Menu](#range-menu)\n- [Example](#example)\n- [Documentation](#documentation)\n- [License](#license)\n\n## Philosophy\n\nTelegram allows you to send a message with a keyboard and edit them. You need to create your action handlers for each keyboard that requires extra logic and state mappers to render buttons with additional data.\n\nThis logic is complicated and requires time to build this simple block - a menu. I searched available APIs and packages and found no suitable solutions. So the motivation of this package is to create an ultimate package that has TypeScript definition, receives and gives state and has I18n support.\n\n## Features\n\n- [x] Perfectly created using TypeScript;\n- [x] State-based. Receives and gives state, no raw buttons;\n- [x] Provides extendable GenericMenu class to build new menu types;\n- [x] It has the available example in source code on GitHub;\n- [x] Simple to use!\n\n## Installing\n\nUsing npm:\n\n```bash\n$ npm install telegraf-menu\n```\n\n## Menu Types\n\n### Regular Menu\n\nRegularMenu allows you to draw a simple menu without logic and handle every button click. Returns button's value.\n\n![regular menu](https://github.com/DrSmile444/telegraf-menu/raw/main/docs/regular-menu.png)\n\nExample code:\n\n```ts\nconst initStartMenu = (ctx: CurrentCtx) =\u003e {\n    new RegularMenu\u003cCurrentCtx, MenuAction\u003e(\n        {\n            action: MenuAction.START,\n            message: 'menu.start.start',\n            filters: START_MENU_FILTERS,\n            replaceable: true,\n            debug: true,\n            menuGetter: (menuCtx) =\u003e menuCtx.session.keyboardMenu,\n            menuSetter: (menuCtx, menu) =\u003e menuCtx.session.keyboardMenu = menu,\n            onChange(changeCtx, state) {\n                switch (state) {\n                    case MenuAction.BASKET:\n                        // return initBasketMenu(changeCtx);\n\n                    case MenuAction.LANGUAGE:\n                        // return initLanguageMenu(changeCtx);\n\n                    case MenuAction.VIDEO_FILTERS:\n                        // return initVideoFiltersMenu(changeCtx);\n                }\n            },\n        },\n    ).sendMenu(ctx);\n};\n```\n\n### Checkbox Menu\n\nCheckboxMenu allows you to draw a checkbox menu and handle onChange, onSubmit, and other hooks. You can choose as many options as you want. Returns array of button values.\n\n![checkbox menu](https://github.com/DrSmile444/telegraf-menu/raw/main/docs/checkbox-menu.png)\n\n```ts\nexport const initBasketMenu = (ctx: CurrentCtx) =\u003e {\n    new CheckboxMenu\u003cCurrentCtx, Basket['fruit']\u003e(\n        {\n            action: MenuAction.BASKET,\n            message: 'menu.basket.start',\n            submitMessage: 'menu.basket.submit',\n            filters: FRUITS_FILTERS,\n            state: ctx.session.basket?.[FruitsFilterType.FRUIT],\n            replaceable: true,\n            menuGetter: (menuCtx) =\u003e menuCtx.session.keyboardMenu,\n            menuSetter: (menuCtx, menu) =\u003e menuCtx.session.keyboardMenu = menu,\n            onSubmit(changeCtx, state) {\n                changeCtx.session.basket[FruitsFilterType.FRUIT] = state;\n                initStartMenu(changeCtx);\n            },\n        },\n    ).sendMenu(ctx);\n};\n```\n\n### Radio Menu\n\nRadioMenu allows you to draw a radio menu and handle onChange, onSubmit, and other hooks. You can choose only one value. Returns button's values.\n\n![radio menu](https://github.com/DrSmile444/telegraf-menu/raw/main/docs/radio-menu.png)\n\nCode example:\n\n```ts\nexport const initLanguageMenu = (ctx: CurrentCtx) =\u003e {\n    new RadioMenu\u003cCurrentCtx, LanguageType\u003e(\n        {\n            action: MenuAction.LANGUAGE,\n            message: 'menu.language.start',\n            submitMessage: 'menu.language.submit',\n            filters: LANGUAGE_FILTERS,\n            state: ctx.session.language,\n            replaceable: true,\n            menuGetter: (menuCtx) =\u003e menuCtx.session.keyboardMenu,\n            menuSetter: (menuCtx, menu) =\u003e menuCtx.session.keyboardMenu = menu,\n            beforeChange(changeCtx, language) {\n                changeCtx.session.language = language;\n                changeCtx.i18n.locale(language);\n            },\n            onSubmit(submitCtx) {\n                initStartMenu(submitCtx);\n            },\n        },\n    ).sendMenu(ctx);\n};\n```\n\n### Range Menu\n\nRangeMenu allows you to draw a range menu and handle onChange, onSubmit, and other hooks. You can choose range values. Returns first and last button values.\n\n![range menu](https://github.com/DrSmile444/telegraf-menu/raw/main/docs/range-menu.png)\n\nCode example:\n\n```ts\nexport const initVideoFiltersMenu = (ctx: CurrentCtx) =\u003e {\n    new RangeMenu\u003cCurrentCtx, VideoFilters\u003e(\n        {\n            action: MenuAction.VIDEO_FILTERS,\n            message: 'menu.videoFilters.start',\n            submitMessage: 'menu.videoFilters.submit',\n            filters: VIDEO_FILTERS,\n            state: ctx.session.videoFilters,\n            replaceable: true,\n            menuGetter: (menuCtx) =\u003e menuCtx.session.keyboardMenu,\n            menuSetter: (menuCtx, menu) =\u003e menuCtx.session.keyboardMenu = menu,\n            onSubmit(changeCtx, state) {\n                changeCtx.session.videoFilters = state;\n                initStartMenu(changeCtx);\n            },\n        },\n    ).sendMenu(ctx);\n};\n```\n\n## Example\n\nTo run a project, you need to set up a bot and sessions.\nAfter that, use GenericMenu middleware in the bot, and you can send your menus!\nA basic setup:\n\n```ts\nimport { Telegraf } from 'telegraf';\nimport { DefaultCtx, GenericMenu, KeyboardButton, MenuFilters } from 'telegraf-menu';\n\nconst bot = new Telegraf(process.env.BOT_TOKEN);\nconst session = new LocalSession({ database: 'local.db.json' });\n\nbot.use(session.middleware());\n\n/**\n * Required callback parser\n * */\nbot.use(GenericMenu.middleware());\n\ntype CurrentCtx = DefaultCtx \u0026 {\n    i18n: I18nContext;\n    session: {\n        videoFilters: {\n            from: string;\n            to: string;\n        },\n        language: LanguageType,\n        basket: Basket;\n        keyboardMenu: GenericMenu,\n    },\n};\n\n\nenum MenuAction {\n    BASKET = 'basket',\n    VIDEO_FILTERS = 'video_filters',\n    LANGUAGE = 'language',\n    START = 'start',\n}\n\nconst START_MENU_FILTERS: MenuFilters\u003cMenuAction\u003e = [\n    new KeyboardButton('menu.start.button.basket', MenuAction.BASKET),\n    new KeyboardButton('menu.start.button.videoFilters', MenuAction.VIDEO_FILTERS),\n    new KeyboardButton('menu.start.button.language', MenuAction.LANGUAGE),\n];\n\nconst initStartMenu = (ctx: CurrentCtx) =\u003e {\n    new RegularMenu\u003cCurrentCtx, MenuAction\u003e(\n        {\n            action: MenuAction.START,\n            message: 'menu.start.start',\n            filters: START_MENU_FILTERS,\n            replaceable: true,\n            debug: true,\n            menuGetter: (menuCtx) =\u003e menuCtx.session.keyboardMenu,\n            menuSetter: (menuCtx, menu) =\u003e menuCtx.session.keyboardMenu = menu,\n            onChange(changeCtx, state) {\n                switch (state) {\n                    case MenuAction.BASKET:\n                        // return initBasketMenu(changeCtx);\n\n                    case MenuAction.LANGUAGE:\n                        // return initLanguageMenu(changeCtx);\n\n                    case MenuAction.VIDEO_FILTERS:\n                        // return initVideoFiltersMenu(changeCtx);\n                }\n            },\n        },\n    ).sendMenu(ctx);\n};\n\n\n/**\n * Menu example\n * */\nbot.command(MenuAction.START, initStartMenu);\nbot.action(new RegExp(MenuAction.START), GenericMenu.onAction(\n    (ctx: CurrentCtx) =\u003e ctx.session.keyboardMenu,\n    initStartMenu,\n));\n```\n\nFull project example is available [here.](https://github.com/DrSmile444/telegraf-menu/tree/main/example)\n\n## Documentation\n\nThe package has TypeScript types and example project where you can test the code.\nIf you have additional comments or suggestions, create a pull request. :)\nThanks!\n\n## License\n\n[MIT](LICENSE)\n\nCreated with ❤ by Dmytro Vakulenko, 2021.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrsmile444%2Ftelegraf-menu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrsmile444%2Ftelegraf-menu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrsmile444%2Ftelegraf-menu/lists"}