Keyboards
A keyboard rides along with a message under the normal reply_markup option. The
options bag mirrors the Telegram API, so reply_markup autocompletes and accepts
a keyboard builder directly — JSON.stringify calls its toJSON() when the
request goes out. Two builders cover the two Telegram keyboards: InlineKeyboard
for buttons attached to a message, ReplyKeyboard for the custom keyboard under
the input field.
This page is the stateless layer — you build a keyboard, hand it over, done. The
Callbacks page owns what happens when an inline button is
pressed (routing the tap to an @Action). Selection-aware keyboards that own
their own state — checkboxes, radio groups, pagination — live in
Stateful keyboards.
Inline keyboards
new InlineKeyboard() accumulates buttons; chained calls build it up. .text()
adds a callback button, .url() a link button, and .row() ends the current
row so the next buttons start a fresh one.
import { Router, Command, Message, InlineKeyboard } from 'nestgram';
@Router()
export class MenuRouter {
@Command('menu')
menu(message: Message) {
const keyboard = new InlineKeyboard()
.text('Buy', 'buy')
.text('Info', 'info')
.row()
.url('Website', 'https://nestgram.vercel.app');
return message.answer('What would you like?', { reply_markup: keyboard });
}
}The second argument to .text() is the button’s callback route — the string
sent back when the button is pressed. Routing that press to a handler (and
carrying typed data in the route, buy/42-style, with no magic strings) is the
Callbacks page; here, just know the string is what identifies
the button.
Beyond .text() and .url(), the everyday button kinds have fluent shortcuts:
| Method | Button |
|---|---|
.text(label, route) | callback button — press sends route back |
.url(label, url) | opens the link |
.webApp(label, url) | opens the Mini App at url |
.switchInline(label, query?) | switch to inline mode in another chat |
.switchInlineCurrent(label, q?) | switch to inline mode in the current chat |
.copyText(label, text) | copies text to the clipboard |
The kinds without a shortcut (a pay button, a login button) are reachable through
.add(...) and the Button value object — see Dynamic keyboards.
The Button value object
A button is also a first-class value: Button. Every Bot API inline-button kind
has a static constructor — Button.text, Button.url, Button.webApp,
Button.switchInline, Button.copyText, Button.loginUrl, Button.pay,
Button.disabled — and the value carries the same callback-route argument as the
fluent method:
import { Button } from 'nestgram';
Button.text('Buy', 'buy/:id', { id: 42 }); // a callback button with a route param
Button.url('Docs', 'https://nestgram.vercel.app');
Button.pay('Pay'); // a kind with no fluent shortcutA Button is immutable: .if(), .else(), .withText() and the colour
modifiers each return a new value, never mutating the original. That is what
makes a button safe to map over a collection and reuse. You hand buttons to a
keyboard through .add(...) or .map(...), both below.
Dynamic keyboards
When the buttons come from data, don’t hand-roll a loop. .map(items, fn) runs
fn per item — return a Button to add it, or a falsy value to skip one — and a
layout method commits the accumulated buttons into rows:
import { InlineKeyboard, Button } from 'nestgram';
interface Product {
id: number;
name: string;
}
export function catalogKeyboard(products: Product[]): InlineKeyboard {
return new InlineKeyboard()
.map(products, (p) => Button.text(p.name, 'buy/:id', { id: p.id }))
.split(2)
.row(Button.url('Catalog', 'https://shop.dev'));
}Buttons accumulate, then a layout method arranges the batch:
| Method | Lays the accumulated buttons out as… |
|---|---|
.split(n) | rows of n (.map(...).split(2) ≡ .text().text().split(2)) |
.spread() | one button per row (.split(1)) |
.row(...btns) | a single row (any buttons passed are added first) |
.group(build) | a block of rows from a sub-builder — for an irregular section |
.add(...buttons) is the universal inlet: it takes Button values straight into
the current row, so the kinds without a fluent shortcut are reachable —
.add(Button.pay('Pay')). Anything .map() returns, .add() accepts too.
Conditional buttons and sections
.if(condition) keeps the last unit — whatever was just produced: a button,
a row, a .split() section, or a .group() — only when condition is true. One
verb covers every scope:
import { InlineKeyboard, Button } from 'nestgram';
interface Item {
id: number;
label: string;
}
export function adminMenu(items: Item[], isAdmin: boolean): InlineKeyboard {
return new InlineKeyboard()
.map(items, (i) => Button.text(i.label, 'pick/:id', { id: i.id }))
.split(3) // a 3-wide grid for everyone
.group((kb) => kb.text('Stats', 'stats').text('Ban', 'ban').split(2))
.if(isAdmin); // ...plus an admin block, only for admins
}.if() consumes the unit either way, so a following .if() can’t re-target it —
.text(...).if(true).if(false) keeps the button.
For the per-item filter inside .map(), condition the single Button with
Button.if(...). Add .else(...) to give it a fallback when hidden — a label
becomes a dead-end button (a no-op press), or pass a full Button:
import { InlineKeyboard, Button } from 'nestgram';
interface Product {
id: number;
name: string;
inStock: boolean;
}
export function shopKeyboard(products: Product[]): InlineKeyboard {
return new InlineKeyboard().map(products, (p) =>
Button.text(p.name, 'buy/:id', { id: p.id }).if(p.inStock).else('Sold out'),
);
}Colouring buttons
Telegram lets a button carry a style: primary (blue), success (green), or
danger (red). On the builder, a colour modifier styles the button just
added — postfix, so it reads like a label on the button it follows:
import { InlineKeyboard } from 'nestgram';
export function confirmKeyboard(): InlineKeyboard {
return new InlineKeyboard()
.text('Confirm', 'confirm')
.success()
.text('Cancel', 'cancel')
.danger()
.text('Later', 'later'); // no modifier → the app's default style
}A Button value styles the same way and returns a new value —
Button.text('Delete', 'del').danger() — so it works inside .map() and
.add() too. The same .primary()/.success()/.danger() modifiers work on a
ReplyKeyboard.
Disabled buttons
A .disabled() button is greyed out and unpressable — Telegram enforces it on
the client, so no callback is ever sent. It takes a condition, which is what
makes it useful inside .map():
import { Button, InlineKeyboard } from 'nestgram';
interface Product {
id: number;
name: string;
inStock: boolean;
}
export function catalogKeyboard(products: Product[]): InlineKeyboard {
return new InlineKeyboard()
.map(products, (product) =>
// In stock: a live buy button. Out of stock: inert, no callback_data.
Button.text(product.name, 'buy/:id', { id: product.id }).disabled(
!product.inStock,
),
)
.split(2);
}This is also what a string .else() produces: .if(inStock).else('Sold out')
shows a live buy button or an inert one, with no route to write either way.
Asking for a written reply
.forceReply() opens Telegram’s reply interface along with the keyboard, so the
user’s next message arrives as a reply to yours. It works on both keyboard kinds
and is a terminal flag, like .resize():
import { InlineKeyboard } from 'nestgram';
export function questionKeyboard(): InlineKeyboard {
return new InlineKeyboard().text('Skip', 'skip').forceReply();
}Useful when a message asks something with both quick answers and a free-form one — the buttons handle the first, the reply box the second.
Editing a keyboard in place
Often you already have a keyboard — the one on the message a button press came
from — and just want to tweak it: relabel a button, drop one, append a row.
InlineKeyboard.from(markup) adopts an existing reply_markup (a deep copy — the
source is left untouched), and you address a button by its route, the same
string that built it:
import { Router, Action, CallbackQuery, Param, InlineKeyboard } from 'nestgram';
@Router()
export class ToggleRouter {
@Action('toggle/:id')
toggle(query: CallbackQuery, @Param('id') id: string) {
if (query.message?.reply_markup === undefined) return;
const next = InlineKeyboard.from(query.message.reply_markup)
.setText(`toggle/${id}`, '☑ Done') // a concrete route → one button
.remove('cancel'); // drop the cancel button
return query.message.editReplyMarkup(next);
}
}The matcher is the load-bearing part. A concrete route (toggle/3) addresses
one button; a template (toggle/:id) addresses every button that fits, with
the captured params handed to the patch. The full set of addressing methods:
| Method | Addresses a button by… |
|---|---|
.setText(matcher, text) | route or predicate → relabel |
.update(matcher, patch) | route or predicate → arbitrary patch |
.replaceText(oldText, newText) | current visible text → relabel |
.remove(matcher) | route or predicate → drop, collapsing empty rows |
.updateAt(row, col, patch) | grid position → patch |
.removeAt(row, col) | grid position → drop |
A predicate matcher is a (button: Button) => boolean, so
.update((b) => b.label === 'Old', …) addresses by anything the Button exposes.
Prefer a route over visible text where you have one — labels drift and get
localised, a route is the stable key.
Reply keyboards
ReplyKeyboard is the same builder shape for the custom keyboard under the input
field. The layout methods (.split(n), .row(), .spread(), .if(cond)) and
the colour modifiers are identical; only the button kinds and the keyboard-level
flags differ:
import { ReplyKeyboard } from 'nestgram';
export function menuKeyboard(): ReplyKeyboard {
return new ReplyKeyboard()
.text('My orders')
.text('Help')
.row()
.text('Settings')
.placeholder('Pick an option…')
.resize()
.oneTime();
}Beyond plain .text(), there is a method per Bot API reply-button kind —
.requestContact(), .requestLocation(), .requestPoll(), .webApp(),
.requestUsers(), .requestChat(). The keyboard-level flags are named for
discoverability but map exactly onto the Telegram markup options:
| Method | Telegram option |
|---|---|
.resize() | resize_keyboard |
.oneTime() | one_time_keyboard |
.persistent() | is_persistent |
.selective() | selective |
.placeholder(t) | input_field_placeholder |
To take a reply keyboard away again, return new RemoveKeyboard() as the
reply_markup:
import { Router, Command, Message, RemoveKeyboard } from 'nestgram';
@Router()
export class DoneRouter {
@Command('done')
done(message: Message) {
return message.answer('Cleared.', { reply_markup: new RemoveKeyboard() });
}
}Where to go next
- Callbacks — route an inline button press to an
@Actionhandler and read its route params. - Stateful keyboards — checkboxes, radio groups, and pagination: keyboards that own a per-message selection and re-render themselves on a tap, with no toggle or nav handler of your own.