When you type a hashtag in the Mastodon web client, you may notice that the system does not always suggest existing tags. This can lead to duplicate tags, reduced post discoverability, and a cluttered tag space. The auto-complete feature helps you select an existing hashtag before you finish typing, which keeps your posts connected to the correct conversation. This article explains how the auto-complete system works, how to use it effectively, and what to do when it does not appear as expected.
Key Takeaways: Mastodon Hashtag Auto-Complete in the Web Client
- Type the # symbol followed by at least 2 characters: Triggers the auto-complete dropdown with matching tags from your instance and federated timeline.
- Use arrow keys or mouse to select a tag: Press Enter or click the tag to insert it into your post.
- Auto-complete only works for tags already known to your instance: Brand new tags may not appear until they are used in at least one post.
How Mastodon Hashtag Auto-Complete Works
The Mastodon web client includes a built-in auto-complete feature for hashtags. When you type the hash symbol followed by at least two characters, the system searches its local database for matching tags. The database includes all hashtags that have appeared in posts on your home instance or in the federated timeline that your instance has seen.
The auto-complete dropdown shows up to five matching tags. Each entry displays the tag name and the number of times it has been used in the last seven days. This count helps you choose the most popular tag for your topic. The dropdown appears below the cursor as you type, and it updates as you add more characters.
The feature is part of the Mastodon web interface code. It does not require any browser extension or additional setup. The same auto-complete logic applies to mentions and emoji, but the hashtag version has its own search index.
Prerequisites for Auto-Complete to Work
A few conditions must be met for the auto-complete dropdown to appear:
- You must be using the official Mastodon web client. Third-party clients such as Tusky or Fedilab have their own auto-complete behavior.
- Your instance must have indexed the tag. If a tag has never been used on your instance or in any federated post your instance has seen, it will not appear in suggestions.
- You must type the hash symbol immediately before the tag text. A space or other character between # and the tag text breaks the trigger.
Using Hashtag Auto-Complete in a New Post
- Open the compose box
Click the compose button or click inside the text area on your home timeline. - Type the hash symbol and the first 2-3 characters of the tag
For example, type #tec to start searching for technology-related tags. The auto-complete dropdown appears after the second character. - Review the suggested tags
Each suggestion shows the tag name and its usage count in the last seven days. Use the arrow keys to move through the list, or click a tag with the mouse. - Select the desired tag
Press Enter or click the tag to insert it into the compose box. The tag is inserted with the correct spelling and without extra spaces. - Continue typing your post
After inserting the tag, you can add more text, other hashtags, or media before posting.
Using Auto-Complete in Replies and Editing
- Reply to a post
Click the reply icon on any post. The compose box opens with the original post quoted. - Position the cursor where you want the hashtag
Click inside the text area at the desired location. Type # followed by the tag characters. - Select from the dropdown
Use the same arrow key or click method to choose the tag. The tag is added inline. - Edit an existing post
Click the three-dot menu on your post and select Edit. The auto-complete works the same way as in a new post.
When Auto-Complete Does Not Appear
Typed fewer than two characters after the hash symbol
The auto-complete system requires at least two characters after the # symbol. If you type only #t, no dropdown appears. Type #te to trigger the search.
Tag does not exist in the local index
If you type #mybrandnewtag and no dropdown appears, the tag has never been used on your instance or in any federated post that your instance has seen. You can still type the tag manually and post it. After the post is published, the tag becomes available for auto-complete for other users on your instance.
Browser extension interferes with the compose box
Some browser extensions that modify text input fields can block the auto-complete dropdown. Try disabling extensions like Grammarly, LastPass, or ad blockers temporarily to see if the dropdown reappears.
Using a third-party client or mobile browser
The auto-complete feature described in this article is specific to the official Mastodon web client on desktop browsers. Mobile browsers and third-party apps may have different behavior. For mobile use, consider using the official Mastodon mobile web interface or an app that supports hashtag suggestions.
Mastodon Hashtag Auto-Complete vs Manual Tagging
| Item | Auto-Complete | Manual Tagging |
|---|---|---|
| Spelling accuracy | Uses exact tag from the database | Depends on user input, may contain typos |
| Discoverability | Connects to an existing tag with followers | May create a duplicate tag with no followers |
| Speed | Select from a list in 1-2 seconds | Type the entire tag manually |
| Tag usage count | Shows popularity before selection | No preview of tag popularity |
| Availability | Only for tags indexed by the instance | Any tag text is accepted |
Best Practices for Using Hashtags with Auto-Complete
Always use the auto-complete dropdown when it appears. This ensures you are using an existing tag that other users are already following. If the tag you want does not appear, consider using a more common synonym or waiting until the tag gains traction. Do not add spaces or punctuation inside the tag text because Mastodon treats spaces as tag separators. Use CamelCase for readability, for example #TechNews instead of #technews.
Limit your post to 3-5 hashtags. Mastodon does not have a strict limit, but too many tags reduce readability and may appear spammy. The auto-complete feature helps you pick the most relevant tags quickly.
Now you can use the hashtag auto-complete feature in the Mastodon web client to choose tags that are already indexed and followed. Start by typing # and two characters in any compose box. If the dropdown does not appear, check that you are on the official web client and that the tag exists in your instance database. For a deeper dive, explore how to follow hashtags directly from the tag page to build a custom timeline.