Keyboard

^{ref / core / Keyboard}

Use this class to simplify building a custom keyboard (something like this: https://core.telegram.org/bots/features#keyboards).

// Build a custom keyboard:
const keyboard = new Keyboard()
  .text('A').text('B').row()
  .text('C').text('D')

// Now you can send it like so:
await ctx.reply('Here is your custom keyboard!', {
  reply_markup: keyboard
})

If you already have some source data which you would like to turn into a keyboard button object, you can use the static equivalents which every button has. You can use them to create a two-dimensional keyboard button array. The resulting array can be turned into a keyboard instance.

const button = Keyboard.text('push my buttons')
const array = [[button]]
const keyboard = Keyboard.from(array)

If you want to create text buttons only, you can directly use a two-dimensional string array and turn it into a keyboard.

const data = [['A', 'B'], ['C', 'D']]
const keyboard = Keyboard.from(data)

Be sure to check out the documentation on custom keyboards in grammY.

^Source

Constructors

Keyboard(keyboard: KeyboardButton[][]);

Initialize a new Keyboard with an optional two-dimensional array of KeyboardButton objects. This is the nested array that holds the custom keyboard. It will be extended every time you call one of the provided methods.

^Source

Properties

is_persistent

is_persistent?: boolean;

Requests clients to always show the keyboard when the regular keyboard is hidden. Defaults to false, in which case the custom keyboard can be hidden and opened with a keyboard icon.

^Source

selective

selective?: boolean;

Show the current keyboard only to those users that are mentioned in the text of the message object.

^Source

one_time_keyboard

one_time_keyboard?: boolean;

Hide the keyboard after a button is pressed.

^Source

resize_keyboard

resize_keyboard?: boolean;

Resize the current keyboard according to its buttons. Usually, this will make the keyboard smaller.

^Source

input_field_placeholder

input_field_placeholder?: string;

Placeholder to be shown in the input field when the keyboard is active.

^Source

Methods

add

add(...buttons: KeyboardButton[]);

Allows you to add your own KeyboardButton objects if you already have them for some reason. You most likely want to call one of the other methods.

^Source

row

row(...buttons: KeyboardButton[]);

Adds a ‘line break’. Call this method to make sure that the next added buttons will be on a new row.

You may pass a number of KeyboardButton objects if you already have the instances for some reason. You most likely don’t want to pass any arguments to row.

^Source

text

text(text: string);

Adds a new text button. This button will simply send the given text as a text message back to your bot if a user clicks on it.

^Source

requestUsers

requestUsers(
  text: string,
  requestId: number,
  options: Omit<KeyboardButtonRequestUsers, "request_id">,
);

Adds a new request users button. When the user presses the button, a list of suitable users will be opened. Tapping on any number of users will send their identifiers to the bot in a “users_shared” service message. Available in private chats only.

^Source

requestChat

requestChat(
  text: string,
  requestId: number,
  options: Omit<KeyboardButtonRequestChat, "request_id">,
);

Adds a new request chat button. When the user presses the button, a list of suitable users will be opened. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.

^Source

requestContact

requestContact(text: string);

Adds a new contact request button. The user’s phone number will be sent as a contact when the button is pressed. Available in private chats only.

^Source

requestLocation

requestLocation(text: string);

Adds a new location request button. The user’s current location will be sent when the button is pressed. Available in private chats only.

^Source

requestPoll

requestPoll(text: string, type?: KeyboardButtonPollType["type"]);

Adds a new poll request button. The user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only.

^Source

webApp

webApp(text: string, url: string);

Adds a new web app button. The Web App that will be launched when the user presses the button. The Web App will be able to send a “web_app_data” service message. Available in private chats only.

^Source

persistent

persistent(isEnabled: boolean);

Make the current keyboard persistent. See https://grammy.dev/plugins/keyboard#persistent-keyboards for more details.

Keyboards are not persistent by default, use this function to enable it (without any parameters or pass true). Pass false to force the keyboard to not persist.

^Source

selected

selected(isEnabled: boolean);

Make the current keyboard selective. See https://grammy.dev/plugins/keyboard#selectively-send-custom-keyboards for more details.

Keyboards are non-selective by default, use this function to enable it (without any parameters or pass true). Pass false to force the keyboard to be non-selective.

^Source

oneTime

oneTime(isEnabled: boolean);

Make the current keyboard one-time. See https://grammy.dev/plugins/keyboard#one-time-custom-keyboards for more details.

Keyboards are non-one-time by default, use this function to enable it (without any parameters or pass true). Pass false to force the keyboard to be non-one-time.

^Source

resized

resized(isEnabled: boolean);

Make the current keyboard resized. See https://grammy.dev/plugins/keyboard#resize-custom-keyboard for more details.

Keyboards are non-resized by default, use this function to enable it (without any parameters or pass true). Pass false to force the keyboard to be non-resized.

^Source

placeholder

placeholder(value: string);

Set the current keyboard’s input field placeholder. See https://grammy.dev/plugins/keyboard#input-field-placeholder for more details.

^Source

toTransposed

toTransposed();

Creates a new keyboard that contains the transposed grid of buttons of this keyboard. This means that the resulting keyboard has the rows and columns flipped.

Note that buttons can only span multiple columns, but never multiple rows. This means that if the given arrays have different lengths, some buttons might flow up in the layout. In these cases, transposing a keyboard a second time will not undo the first transposition.

Here are some examples.

original    transposed
[  a  ]  ~> [  a  ]

            [  a  ]
[a b c]  ~> [  b  ]
            [  c  ]

[ a b ]     [a c e]
[ c d ]  ~> [ b d ]
[  e  ]

[ a b ]     [a c d]
[  c  ]  ~> [ b e ]
[d e f]     [  f  ]

^Source

toFlowed

toFlowed(columns: number, options: FlowOptions);

Creates a new keyboard with the same buttons but reflowed into a given number of columns as if the buttons were text elements. Optionally, you can specify if the flow should make sure to fill up the last row.

This method is idempotent, so calling it a second time will effectively clone this keyboard without reordering the buttons.

Here are some examples.

original    flowed
[  a  ]  ~> [  a  ]    (4 columns)

            [  a  ]
[a b c]  ~> [  b  ]    (1 column)
            [  c  ]

[ a b ]     [a b c]
[ c d ]  ~> [ d e ]    (3 columns)
[  e  ]

[ a b ]     [abcde]
[  c  ]  ~> [  f  ]    (5 columns)
[d e f]

[a b c]     [  a  ]
[d e f]  ~> [b c d]    (3 colums, { fillLastRow: true })
[g h i]     [e f g]
[  j  ]     [h i j]

^Source

clone

clone(keyboard: KeyboardButton[][]);

Creates and returns a deep copy of this keyboard.

Optionally takes a new grid of buttons to replace the current buttons. If specified, only the options will be cloned, and the given buttons will be used instead.

^Source

append

append(...sources: KeyboardSource[]);

Appends the buttons of the given keyboards to this keyboard. If other options are specified in these keyboards, they will be ignored.

^Source

build

build();

Returns the keyboard that was build. Note that it doesn’t return resize_keyboard or other options that may be set. You don’t usually need to call this method. It is no longer useful.

^Source

Static Methods

text

text(text: string): KeyboardButton.CommonButton;

Creates a new text button. This button will simply send the given text as a text message back to your bot if a user clicks on it.

^Source

requestUsers

requestUsers(
  text: string,
  requestId: number,
  options: Omit<KeyboardButtonRequestUsers, "request_id">,
): KeyboardButton.RequestUsersButton;

Creates a new request users button. When the user presses the button, a list of suitable users will be opened. Tapping on any number of users will send their identifiers to the bot in a “users_shared” service message. Available in private chats only.

^Source

requestChat

requestChat(
  text: string,
  requestId: number,
  options: Omit<KeyboardButtonRequestChat, "request_id">,
): KeyboardButton.RequestChatButton;

Creates a new request chat button. When the user presses the button, a list of suitable users will be opened. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.

^Source

requestContact

requestContact(text: string): KeyboardButton.RequestContactButton;

Creates a new contact request button. The user’s phone number will be sent as a contact when the button is pressed. Available in private chats only.

^Source

requestLocation

requestLocation(text: string): KeyboardButton.RequestLocationButton;

Creates a new location request button. The user’s current location will be sent when the button is pressed. Available in private chats only.

^Source

requestPoll

requestPoll(text: string, type?: KeyboardButtonPollType["type"]): KeyboardButton.RequestPollButton;

Creates a new poll request button. The user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only.

^Source

webApp

webApp(text: string, url: string): KeyboardButton.WebAppButton;

Creates a new web app button. The Web App that will be launched when the user presses the button. The Web App will be able to send a “web_app_data” service message. Available in private chats only.

^Source

from

from(source: KeyboardSource): Keyboard;

Turns a two-dimensional keyboard button array into a keyboard instance. You can use the static button builder methods to create keyboard button objects.

^Source