Skip to main content

​
Overview

Custom slugs let you choose your own short code instead of the automatically generated 8-character nanoid. This creates memorable, branded links like yoursite.com/spring-sale instead of yoursite.com/aB3xY7kL.
Custom slugs are only available to authenticated users. Sign in or create an account to use this feature.

​
Why Use Custom Slugs?

Custom slugs make your links:
  • Memorable: yoursite.com/contact is easier to remember than yoursite.com/xK9mP2nQ
  • Branded: Reinforce your brand with recognizable slugs
  • Professional: Clean, readable links look more trustworthy
  • Campaign-friendly: Track specific campaigns with descriptive slugs like summer-2024
1

Sign in to your account

Custom slugs require authentication. If you don’t have an account, see the Authentication guide first.
2

Navigate to the home page

Go to the home page where you’ll see the URL shortening form.
3

Enter your URL and custom slug

Paste your long URL and enter your desired custom slug in the “Custom slug (optional)” field.
4

Click Shorten

shrtnr validates your slug, checks for conflicts, and creates your custom short link.

​
Slug Validation Rules

Custom slugs must follow these requirements:

​
Character Requirements

  • Allowed characters: Letters (a-z, A-Z), numbers (0-9), hyphens (-), and underscores (_)
  • Length: 1 to 20 characters
  • No spaces: Use hyphens or underscores instead
// Validation regex from app/lib/links.ts:9
const SLUG_REGEX = /^[a-zA-Z0-9_-]{1,20}$/;

​
Valid Examples

  • spring-sale
  • contact_us
  • 2024promo
  • q1-report
  • beta

​
Invalid Examples

SlugReasonFix
my slugContains spacesUse my-slug or my_slug
special!Invalid character !Use only letters, numbers, -, _
this-is-a-very-long-slug-nameOver 20 charactersShorten to 20 characters or less
“ (empty)No charactersProvide at least 1 character
apiReserved routeChoose a different slug
If your slug is invalid, you’ll receive the error: “Invalid slug: use letters, numbers, _ and - only (1–20 chars)”.

​
Reserved Slugs

Certain slugs are reserved for application routes and cannot be used:
  • api
  • shorten
  • login
  • register
  • dashboard
  • _next
  • favicon.ico
// From app/[shortCode]/route.ts:4
const RESERVED = new Set(['api', 'shorten', 'login', 'register', 'dashboard', '_next', 'favicon.ico']);

​
Uniqueness Checking

shrtnr ensures every custom slug is unique:
  1. Before creating a link, the database is checked for existing slugs
  2. If the slug already exists, creation fails with “Slug already in use”
  3. Slugs are case-sensitive: MyLink and mylink are different
Once a slug is taken, it cannot be used again - even if the original link is deleted. Choose your slugs carefully.

​
Editing Custom Slugs

You can change your custom slug after creation:
1

Open the dashboard

Navigate to your dashboard (see Dashboard guide) to see all your links.
2

Click Edit

Find the link you want to modify and click the Edit button.
3

Update the slug

Change the custom slug field to your new desired slug.
4

Save changes

Click Save. The old slug is released and your link now uses the new slug.
// From app/dashboard/page.tsx:90-93
body: JSON.stringify({
  shortCode: editSlug.trim() || undefined,
  expiresAt: editExpires ? editExpires.toISOString() : null,
})
When you edit a slug, the old short link stops working immediately. Anyone using the old link will get a 404 error.
You can convert an automatically generated short code to a custom slug:
  1. Create a link without a custom slug (get the 8-character nanoid)
  2. Open the link in your dashboard
  3. Click Edit and enter your custom slug
  4. Save - your link now uses the custom slug
This is useful when you create a link quickly and want to brand it later.

​
Cache Invalidation

When you create or update a custom slug, shrtnr automatically invalidates the Redis cache:
  • Old slug cache entry is deleted
  • New slug cache is populated on first use
  • Ensures redirects always use the latest configuration
// From app/lib/links.ts:149-150
await redis.del(`${REDIS_PREFIX}${oldCode}`);
await redis.del(`${REDIS_PREFIX}${slug}`);

​
Best Practices

Custom Slug Guidelines

Do:
  • Use descriptive, memorable names
  • Keep slugs short and simple
  • Use hyphens for readability (spring-sale not springsale)
  • Match campaign names for easy tracking
  • Test that your slug isn’t already taken
Don’t:
  • Use random or meaningless combinations
  • Make slugs too long (aim for under 15 characters)
  • Include spaces or special characters
  • Use reserved route names
  • Change slugs for widely-distributed links

​
Common Errors

​
”Sign in to use a custom slug”

You tried to create a custom slug as a guest user. Solution: See the Authentication guide to sign in or create an account.

​
”Slug already in use”

Another link (yours or someone else’s) is already using this slug. Solution: Choose a different slug. Try adding a number or year: promo → promo-2024.

​
”Invalid slug: use letters, numbers, _ and - only (1–20 chars)”

Your slug contains invalid characters or is too long. Solution: Remove special characters, spaces, or shorten to 20 characters max.

​
Examples

​
Marketing Campaign

Original: https://example.com/products/category/spring-collection-2024?utm_source=email
Custom slug: spring-2024
Short link: yoursite.com/spring-2024

​
Event Registration

Original: https://eventbrite.com/event/12345678/register?discount=earlybird
Custom slug: webinar-march
Short link: yoursite.com/webinar-march

​
Social Media Bio

Original: https://linktr.ee/yourprofile
Custom slug: links
Short link: yoursite.com/links

Build docs developers (and LLMs) love

Get started for freeTalk to us