Tutorials

XenForo Custom BBCode: Create a Tag in the Admin CP

Build a styled box tag with the built-in BB code form, no PHP needed. See what the form can and cannot limit, and how posters can become thumbnails.

D.C Style · 7 min read
Share on X
Illustration of a colored box and button inside a forum editor window framed by square brackets.
On this page

You can create a XenForo custom BBCode in the Admin CP with a simple form. You give the tag a name, write a little HTML, and XenForo turns the tag into that HTML in posts. This guide builds a colored box, step by step, with no PHP.

BBCode is the square-bracket markup members type in posts, like [B]bold[/B]. XenForo calls your own tags "custom BB codes". They are managed in one place, and the official manual covers every field on the form.

How to add a custom BBCode in XenForo

The short version has five steps. We go through each one below.

  1. Open the custom BB code manager in the Admin CP and start a new code.
  2. Enter the tag keyword and a title.
  3. Set the replacement mode to simple replacement.
  4. Decide if the tag takes an option, such as a color.
  5. Write the HTML replacement and save.

The manual's own example is a BOX tag titled "Colored box". It turns [BOX="red"]text[/BOX] into a div with a red background. We will use the same example, because it shows every important idea.

Note:
The manual page does not say which XenForo version it describes, so check each field against your own form. We have not confirmed differences between 2.2 and 2.3.

Where BBCode settings live in the Admin CP

XenForo has a custom BB code manager. It lists every custom tag. From there you can create a new one, delete one, or switch one off for a while with the toggle. The menu path can differ between installs, so we won't guess it. Look for BB codes in the Admin CP, or use the Admin CP search box.

At the top of the manager you will also find import and export controls. They move several custom BB codes at once. That is handy when you build a tag on a test forum and want the same tag on your live forum.

A separate tool, the BB code button manager, controls where buttons sit in the message editor. We come back to it later.

Build a simple tag with replacement text

This is the XenForo BBCode replacement itself: the HTML that stands in for your tag. Create a new code and fill in these fields.

FieldWhat to enter
BB code tagBOX
TitleColored box
Replacement modeSimple replacement

The "BB code tag" is the keyword members type between the brackets. The title is the name you and your staff see in the Admin CP.

"Replacement mode" offers two choices: a simple replacement or a PHP callback. The callback uses the Class and Method fields. The manual calls it mostly a developer option, so stay with simple replacement.

Now the "HTML replacement" field. It uses two tokens. {text} is whatever sits inside the tag. {option} is the value after the equals sign. Enter this:

<div style="background-color: {option}">{text}</div>

Save it. A member can now type [BOX="red"]Read the rules first.[/BOX] and get a red box with that sentence inside.

Fill in the example boxes

The "Example usage and output" boxes take a sample input and the output it produces. They are optional, but worth a minute. They show your staff how the tag is meant to be used.

Add options and a parameter

The setting "Supports option parameter" can be Yes, Optional or No. In the box example it is Yes, because the member supplies a color. Pick the value that fits your tag.

  • Yes: the tag always needs an option, like [BOX="red"].
  • Optional: the tag works with or without one.
  • No: the tag takes only text, like a plain highlight.

Keep options safe

The option value goes into your HTML, so limit what members can enter. The advanced field "Option match regular expression" limits which option values are accepted. A regular expression is a short pattern that describes allowed text. For a color tag, you could allow only color names or hex codes.

Warning:
Don't leave an option open to any text if it goes into your HTML. Use the match field to allow only the values you expect.

Other advanced options

The "Within this BB code" settings can switch off smilie parsing, line-break conversion and link auto-parsing inside the tag. They can also stop other BB codes being parsed inside it. "Trim line breaks after" removes extra whitespace after the tag, and a value of 0 allows no extra line breaks. "HTML email and text replacements" give alternative output for HTML emails and plain text, using the same tokens.

Choose who can use the tag

Here is the honest part. The form in the manual has no per-tag user group setting. The only restriction on it is the checkbox "Allow this BB code in signatures". Leave it unchecked to keep the tag out of user signatures.

That means we can't promise XenForo BBCode permissions per user group from the built-in form. We found no source for one, so we won't describe a setting that may not exist. If you need a tag for staff only, you have a few options:

  • Don't give the tag an editor button, and share the syntax with staff only. This hides it but does not block it.
  • Keep the tag out of signatures with the checkbox.
  • Ask a developer for a callback, or look for an add-on that adds user group limits.

A tag without a button still works for anyone who types it by hand, so it is not real access control.

Test it in the editor and on mobile

The "Editor icon" field controls the editor button. Enter a Font Awesome icon or an image, and members get a button that inserts the tag. Leave it as None and the tag works only when typed by hand.

To move the button, use the BB code button manager. It sets where the custom button and the other editor controls sit.

  1. Post a test message in a private or staff forum using your tag.
  2. Check the preview and the saved post.
  3. Click the editor button, if you added one, and confirm it inserts the right text.
  4. Open the same thread on a phone and check the box fits the screen.

We found no official guidance on mobile testing, so treat the last step as a habit.

Use custom BBCode posters as thread thumbnails

Some custom tags render a poster image, such as a movie poster. The free Thumbnail add-on can use posters rendered by the custom BBCode tags you configure in its options as thread thumbnails.

Thumbnail needs XenForo 2.3 or later. Version 1.0.7 changed it to build thumbnails from configured custom BBCode tags, including TMDB and IMDb tags. It can also fetch movie and TV posters through TMDB when a tag does not render an image. That lookup uses your own TMDB API read token.

Posters take priority during automatic selection, and manual thumbnail choices stay protected. To change the order, use the setting Thumbnail selection priority under Setup → Options → D.C Style - Thumbnail. For setup steps, see the guide to setting up Thumbnail.

Common mistakes and fixes

  • The tag shows as plain text. Check that the tag is enabled in the manager and the keyword matches what you typed.
  • The color doesn't apply. Make sure "Supports option parameter" is not set to No.
  • The tag appears in signatures. Untick "Allow this BB code in signatures".
  • Extra blank space after the tag. Set "Trim line breaks after" to 0.
  • The option accepts odd values. Add a pattern in "Option match regular expression".

If you want your tag's HTML to look better, you may need CSS in your style. Our guide on customizing templates safely shows how to do that without losing changes on upgrade.

What to do next

Create the BOX tag on a test forum first. Check it in the editor and on your phone. Then decide who should have it, keeping in mind that the form has no user group setting. If you run a film or TV forum, try Thumbnail so your poster tags show up in thread lists. For more how-to posts, browse the Tutorials category. The full field list is in the XenForo BB code manual.

Sources