Table of Contents

IRC Formatting

This document describes what I consider to be almost universally understood formatting. It is a living specification which is updated in response to feedback and implementations as they change.

If I've missed out on some formatting character or method which is understood by a majority of IRC software in use today, or have made a mistake in this document, please open an issue or contact me.


Introduction

IRC clients today understand a number of special formatting characters. These characters allow IRC software to send and receive colors and formatting codes such as bold, italics, underline and others.

Over the years, many clients have attempted to create their own methods of formatting and there have been variations and extensions of almost every method. However, the characters and codes described in this document are understood fairly consistently across clients today.

Following what’s described in this document should let your software send and interpret formatting in a fairly sane way, consistent with how most other IRC software out there does. Using formatting characters and methods not described in this document is possible, but it should be assumed they will not work across most clients (unless there is some way to fall back to what’s defined here).

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.


Formatting Uses

Formatting is widely used in IRC. In this section, we outline the places where formatting is traditionally used by clients and allowed by servers. This is not an expansive list nor does it note everywhere formatting is used, just some of the most common places.

Messages / Numerics

Formatting characters can be used in lots of IRC messages and numerics. This is not a complete list, just some of the messages formatting codes are used with most often.

These are some of the messages and features formatting codes are normally used with:

And the numerics containing content associated with these messages and features.

Names

Formatting is allowed and commonly used in realnames (set with the USER command when the client joins the network).

On some networks and with some server software, vhosts (vanity hostnames) may contain formatting characters and codes. Hostnames sent to clients MAY contain formatting, and clients SHOULD display them with this in mind.

The use of formatting MUST NOT be allowed in nicknames, user names or channel names. This is to avoid confusion and prevent issues, particularly with clients that have disabled the rendering of colors / formatting or cannot display certain types of formatting.

If a client sends a USER command with any formatting codes in the first parameter (in the username) during registration, the server SHOULD send the client an ERROR message and close the connection.


Client Behaviour

This section is non-normative and outlines suggested behaviour for clients and client interfaces.

Limitations

If an IRC client cannot display a specified type of formatting, the client should do one of the following:

  • Simply not display the formatting.
  • Display the formatting character in an obvious way, so users are aware that it was used.

One way some clients represent formatting characters they cannot display is using an uppercase letter which represents the specific formatting character, with their default foreground and background colors switched. For example, displaying an underline formatting character as U.

Preventing Display of Formatting

Clients may allow users to prevent all or just specified formatting from displaying. This can help users that are colorblind or are visually impared, and should be considered by client authors.

ANSI Escape Code Support

IRC clients supporting ANSI formatting was, historically, due to clients outputting messages via terminals that supported ANSI escape codes. Many IRC clients today do not display through an interface that natively supports ANSI escape codes, and so must implement this behaviour themselves if they wish to support it.

Clients can support or not support ANSI escape codes as they like. However, they should implement this feature with the knowledge that a large number of IRC clients today, even those using a terminal interface, do not support displaying text formatted using ANSI escape codes.


Characters

There are a number of formatting characters that are parsed and understood by IRC software today.

Some formatting codes work as a toggle, i.e. with the first instance of the character, the specified formatting is enabled for the following text. After the next instance of that character, that formatting is disabled for the following characters. Formatting codes that work in this way are called ‘togglable’.

These formatting characters are the ones all IRC clients should understand.

Bold

ASCII 0x02

This formatting character works as a toggle. It enables bold text (i.e. bold text).

Italics

ASCII 0x1D

This formatting character works as a toggle. It enables italicized text (i.e. italicised text).

Underline

ASCII 0x1F

This formatting character works as a toggle. It enables underlined text (i.e. underlined text).

Color

ASCII 0x03

This formatting character sets or resets colors on the following text.

With this formatting code, colors are represented as ASCII digits.

Forms of Color Codes

In the following list, <CODE> represents the color formatting character (0x03), <COLOR> represents one or two ASCII digits (either 0-9 or 00-15).

The use of this code can take on the following forms:

  • <CODE> - Reset foreground and background colors.
  • <CODE>, - Reset foreground and background colors and display the , character as text.
  • <CODE><COLOR> - Set the foreground color.
  • <CODE><COLOR>, - Set the foreground color and display the , character as text.
  • <CODE><COLOR>,<COLOR> - Set the foreground and background color.

The foreground color is the first <COLOR>, and the background color is the second <COLOR> (if sent).

If only the foreground color is set, the background color stays the same.

If there are two ASCII digits available where a <COLOR> is allowed, if the two characters are in the range 00-15 then two characters MUST always be read for it. If they are in the range 16-99, the client MAY unconditionally read and process the two characters, or the client MAY read just the first digit and display the second digit.

Clients SHOULD NOT send the digits 16-99 where a <COLOR> is allowed, as clients will interpret it differently.

Colors

The following colors are defined for use with this formatting character:

  •    - 00 - White.
  •    - 01 - Black.
  •    - 02 - Blue.
  •    - 03 - Green.
  •    - 04 - Red.
  •    - 05 - Brown.
  •    - 06 - Magenta.
  •    - 07 - Orange.
  •    - 08 - Yellow.
  •    - 09 - Light Green.
  •    - 10 - Cyan.
  •    - 11 - Light Cyan.
  •    - 12 - Light Blue.
  •    - 13 - Pink.
  •    - 14 - Grey.
  •    - 15 - Light Grey.
  •    - 99 - Default Foreground/Background - Not universally supported.
NOTE: The colors displayed here are simply a guide. The actual RGB values used for these codes will depend on what the client author has defined, and are often defined by the terminal color scheme for terminal-based clients.
WARNING: Clients SHOULD NOT send color codes 16-99. As noted above, they will be interpreted different ways by different clients and we do not recommend using them.

Mistaken Eating of Text

When sending color codes 0-9, clients may use either the one-digit (3) or two-digit (03) versions of it. However, since two digits are always used if available, if the text following the color code starts with a digit, the last <COLOR> MUST use the two-digit version to be displayed correctly. This ensures that the first character of the text does not get interpreted as part of the formatting code.

If the text immediately following a code setting a foreground color consists of something like ",13", it will get interpreted as setting the background rather than text. In this example, clients can put the color code either after the comma character or before the character in front of the comma character to avoid this. They can also put a different formatting code after the comma to ensure that the number does not get interpreted as part of the color code (for instance, two bold characters in a row, which will cancel each other out as they are toggles).

Hex Color

ASCII 0x04

Some clients support an alternate form of conveying colours using hex codes.

Following this character are six hex digits representing the Red, Green and Blue values of the colour to display (e.g. FF0000 means bright red).

Keep the Forms of Color Codes section above in mind, as this method of formatting keeps these same rules – the exceptions being that <CODE> represents the hex color character (0x04) and <COLOR> represents a six-digit hex value as RRGGBB.

This method of formatting is not as widely-supported as the colors above, but clients are fine to parse them without any negative effects.

Reverse Color (/ or Italics)

ASCII 0x16

This formatting character switches the foreground and background colors of the following text. It can act similarly to a toggle, in that every time it is used it switches the colors for the text following it.

WARNING: As noted in the title of this section, (0x16) may also represent italics in some clients (those clients that do usually represent Reverse Color with the character (0x12) instead). Honestly, it's probably about half-half (two of the major clients I checked both handled this differently), so I'd recommend not using this code.

Reset

ASCII 0x0F

This formatting character resets all formatting. It removes the bold, italics, and underline formatting, and sets the foreground and background colors back to the default for the client display. The text following this character will use or display no formatting, until other formatting characters are encountered.


Examples

In this section, the color formatting character (0x03) is displayed as C, the bold character (0x02) is displayed as B, the italics character (0x1D) is displayed as I, and the reset character (0x0F) is displayed as O.

Each example displays both the raw IRC code sent, and then a formatted version of the output.

  • Code:   I love C3IRC! CIt is the C7best protocol ever!
    Output: I love IRC! It is the best protocol ever!
  • Code:   This is a IC13,9cool Cmessage
    Output: This is a cool message
  • Code:   IRC Bis C4,12so CgreatO!
    Output: IRC is so great!
  • Code:   Rules: Don't spam 5C13,8,6C,7,8, and especially not B9BI!
    Output: Don't spam 5,6,7,8, and especially not 9!