Elisp: How to Create Keymap for Major Mode

By Xah Lee. Date: . Last updated: .

This page shows you how to define keys in your own major mode.

Each major mode typically define many of its own keys for calling the major mode's commands. (by convention, major mode's keys start with Ctrl+c Ctrl+key )

Here's how to define the keys for major mode:

;; sample major mode with its own keymap

;; ----------------------------------------
;; commands

(defun my-mode-cmd1 ()
  "do something"
  (message "cmd1 called"))

(defun my-mode-cmd2 ()
  "do something"
  (message "cmd2 called"))

(defun my-mode-cmd3 ()
  "do something"
  (message "cmd3 called"))

(defun my-mode-cmd4 ()
  "do something"
  (message "cmd4 called"))

;; ----------------------------------------
;; keybinding

(defvar my-mode-map nil "Keymap for `my-mode-mode'")
;; make sure that the var name is your mode name followed by -map. That way, define-derived-mode will automatically set it as local map

;; also, by convention, variable names for keymap should end in -map

  (setq my-mode-map (make-sparse-keymap))

  (define-key my-mode-map (kbd "C-c C-a") 'my-mode-cmd1)

  (define-key my-mode-map (kbd "C-c C-b") 'my-mode-cmd2)

  (define-key my-mode-map (kbd "C-c C-c") 'my-mode-cmd3)

  (define-key my-mode-map (kbd "C-c C-d") 'my-mode-cmd4)

  ;; by convention, major mode's keys should begin with the form C-c C-‹key›
  ;; by convention, keys of the form C-c ‹letter› are reserved for user. don't define such keys in your major mode

;; ----------------------------------------
;; define the mode

(define-derived-mode my-mode prog-mode "my"
  "my-mode is a major mode for editing language my.


  ;; actually no need
  (use-local-map my-mode-map) ; if your keymap name is modename follow by -map, then this line is not necessary, because define-derived-mode will find it and set it for you

  1. Copy and paste the above code into a buffer.
  2. Then, Alt+x eval-buffer.
  3. Then, open a new buffer. Call my-mode to activate it.
  4. Then, Alt+x describe-mode.

You'll see this:

emacs sample-describe-mode

You can also press one of the keys to see the command being called.

How Does it Work?

To have keybinding for a major mode, the 2 essential steps are:

  1. Define a keymap.
  2. Use (use-local-map keymap_var_name) in your mode body, so that when the command is called, it sets a local keymap in user's current buffer. (this step may be implicitly done for you by define-derived-mode).

The typical way to define a keymap is this:

(defvar my-mode-map nil "keymap for `my-mode-mode'")

(setq my-mode-map (make-sparse-keymap))

(define-key my-mode-map (kbd "C-c C-a") 'my-mode-cmd1)

(define-key my-mode-map (kbd "C-c C-b") 'my-mode-cmd2)

(define-key my-mode-map (kbd "C-c C-c") 'my-mode-cmd3)

;; and more

Keybinding Syntax

For key syntax and related question about keys, see:

Emacs: How to Define Keys

See also:

Elisp, Writing Major Mode

  1. Syntax Coloring
  2. Font Lock Mode
  3. Define Face
  4. Color Comment
  5. Comment Command
  6. Your Own Comment Command
  7. Keyword Completion Command
  8. Create Keymap
  9. Abbrev/Template
  10. Text Properties
  11. Overlay Highlighting
  12. Lookup Doc
  13. Syntax Table

  1. How to Name Your Major Mode
  2. provide, require, features
  3. load, load-file, autoload

If you have a question, put $5 at patreon and message me.
Or Buy Xah Emacs Tutorial
Or buy a nice keyboard: Best Keyboards for Emacs


Emacs Lisp