Emacs Lisp: 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.

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

;; sample major mode with its own keymap

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

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

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

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

(defun my-mode-cmd4 ()
  "do something"
  (interactive)
  (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

(progn
  (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.

\\{my-mode-map}"

  ;; 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, call eval-buffer.
  3. Then, open a new buffer. Call my-mode to activate it.
  4. Then, call 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:

Like it? Buy Xah Emacs Tutorial. Thanks.

or, buy something from Best Keyboard for Emacs