Alias Sorting · Unhead

[Unhead Home](https://unhead.unjs.io/ "Home")

- [Docs](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/overview)
- [Tools](https://unhead.unjs.io/tools)
- [Learn](https://unhead.unjs.io/learn/guides/what-is-capo)

[Releases](https://unhead.unjs.io/releases)

Search…```k`` /`

[Unhead on GitHub](https://github.com/unjs/unhead)

[User Guides](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/overview)

[API](https://unhead.unjs.io/docs/nuxt/head/api/get-started/overview)

[Releases](https://unhead.unjs.io/docs/nuxt/releases/v3)

Nuxt

- [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/head/guides/plugins/alias-sorting)
- [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/head/guides/plugins/alias-sorting)
- [Switch to Vue](https://unhead.unjs.io/docs/vue/head/guides/plugins/alias-sorting)
- [Switch to React](https://unhead.unjs.io/docs/react/head/guides/plugins/alias-sorting)
- [Switch to Svelte](https://unhead.unjs.io/docs/svelte/head/guides/plugins/alias-sorting)
- [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/head/guides/plugins/alias-sorting)
- [Switch to Angular](https://unhead.unjs.io/docs/angular/head/guides/plugins/alias-sorting)

v3 (stable)

Head

- [Discord Support](https://discord.com/invite/275MBUBvgP)

- Get Started
  - [Overview](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/overview)
  - [Introduction to Unhead](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/intro-to-unhead)
  - [Starter Recipes](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/starter-recipes)
  - [Installation](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/installation)
  - [Upgrade Guide](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/migration)
- Core Concepts
  - [Titles & Title Templates](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/titles)
  - [Tag Sorting & Placement](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/positions)
  - [Class & Style Attributes](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/class-attr)
  - [Inline Style & Scripts](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/inner-content)
  - [Tag Deduplication](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/handling-duplicates)
  - [DOM Event Handling](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/dom-event-handling)
  - [Script Loading](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/loading-scripts)
  - [Context & Reactivity](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/reactivity)
  - [Components](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/components)
- Build Plugins
  - [Overview](https://unhead.unjs.io/docs/nuxt/head/guides/build-plugins/overview)
  - [Tree-Shaking](https://unhead.unjs.io/docs/nuxt/head/guides/build-plugins/tree-shaking)
  - [useSeoMeta Transform](https://unhead.unjs.io/docs/nuxt/head/guides/build-plugins/seo-meta-transform)
  - [Minify Transform](https://unhead.unjs.io/docs/nuxt/head/guides/build-plugins/minify-transform)
  - [Devtools](https://unhead.unjs.io/docs/nuxt/head/guides/build-plugins/devtools)
- Plugins
  - [Template Params](https://unhead.unjs.io/docs/nuxt/head/guides/plugins/template-params)
  - [Alias Sorting](https://unhead.unjs.io/docs/nuxt/head/guides/plugins/alias-sorting)
  - [Canonical Plugin](https://unhead.unjs.io/docs/nuxt/head/guides/plugins/canonical)
  - [Infer SEO Meta](https://unhead.unjs.io/docs/nuxt/head/guides/plugins/infer-seo-meta-tags)
  - [Minify](https://unhead.unjs.io/docs/nuxt/head/guides/plugins/minify)
  - [Validate](https://unhead.unjs.io/docs/nuxt/head/guides/plugins/validate)

Plugins

# Alias Sorting

[Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/1.guides/plugins/alias-sorting.md)

Last updated Apr 9, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [refactor(bundler)!: named Unhead export, ctx-based transforms, dev-mode validate (#733)](https://github.com/unjs/unhead/pull/733).

On this page

- [What Is Alias Sorting?](#what-is-alias-sorting)
- [Why Use Aliases Instead of Numbers?](#why-use-aliases-instead-of-numbers)
- [How Do I Set Up Alias Sorting?](#how-do-i-set-up-alias-sorting)
- [How Do I Use Alias Sorting?](#how-do-i-use-alias-sorting)
- [Common Use Cases](#common-use-cases)
- [Best Practices](#best-practices)
- [Related](#related)

**Quick Answer:** The Alias Sorting plugin lets you control head tag order using readable `before:` and `after:` prefixes instead of arbitrary numbers. Use `tagPriority: 'before:script:analytics'` to place a script before another.

## [What Is Alias Sorting?](#what-is-alias-sorting)

The Alias Sorting plugin lets you control tag order using descriptive `before:` and `after:` prefixes instead of numerical priorities.

## [Why Use Aliases Instead of Numbers?](#why-use-aliases-instead-of-numbers)

Numerical priorities become hard to maintain as your application grows:

- Numbers are arbitrary and their meaning isn't clear
- You need to know all existing priorities to insert a new tag
- Changing one priority might require updating many others

Aliases make tag ordering more intuitive and maintainable with declarative relationships between tags.

## [How Do I Set Up Alias Sorting?](#how-do-i-set-up-alias-sorting)

Add the plugin to your Unhead configuration:

Input

```
import { createHead } from '#imports'
import { AliasSortingPlugin } from '#imports/plugins'

const head = createHead({
  plugins: [
    AliasSortingPlugin()
  ]
})
```

## [How Do I Use Alias Sorting?](#how-do-i-use-alias-sorting)

### [Basic Ordering](#basic-ordering)

Use `before:` or `after:` with the tag type and key:

Input

```
useHead({
  // First script
  script: [{
    key: 'analytics',
    src: '/analytics.js'
  }],
})

useHead({
  // This will render before analytics.js
  script: [{
    src: '/critical.js',
    tagPriority: 'before:script:analytics'
  }]
})
```

Output

```
<script src="/critical.js"></script>
<script src="/analytics.js"></script>
```

### [What Is the Alias Format?](#what-is-the-alias-format)

The format is: `{before|after}:{tagName}:{key}`

For example:

- `before:script:analytics` - Place before the analytics script
- `after:meta:description` - Place after the description meta tag
- `before:link:styles` - Place before the styles link tag

### [Multiple Dependencies](#multiple-dependencies)

You can order multiple tags relative to each other:

Input

```
useHead({
  script: [
    {
      key: 'third',
      src: '/c.js',
      tagPriority: 'after:script:second'
    },
    {
      key: 'second',
      src: '/b.js',
      tagPriority: 'after:script:first'
    },
    {
      key: 'first',
      src: '/a.js'
    }
  ]
})
```

Output

```
<script src="/a.js"></script>
<script src="/b.js"></script>
<script src="/c.js"></script>
```

### [Can I Combine Aliases with Numeric Priorities?](#can-i-combine-aliases-with-numeric-priorities)

Yes. Alias sorting works alongside numeric priorities. The plugin will preserve the numeric priority of the referenced tag:

Input

```
useHead({
  script: [
    {
      key: 'high-priority',
      src: '/important.js',
      tagPriority: 0
    },
    {
      src: '/also-important.js',
      tagPriority: 'before:script:high-priority'
      // Will inherit priority 0 and render first
    }
  ]
})
```

## [Common Use Cases](#common-use-cases)

### [How Do I Load Critical CSS First?](#how-do-i-load-critical-css-first)

Ensure critical CSS is loaded before other stylesheets:

Input

```
useHead({
  link: [
    {
      key: 'main-css',
      rel: 'stylesheet',
      href: '/css/main.css'
    },
    {
      key: 'critical-css',
      rel: 'stylesheet',
      href: '/css/critical.css',
      tagPriority: 'before:link:main-css'
    }
  ]
})
```

### [How Do I Control Script Loading Order?](#how-do-i-control-script-loading-order)

Control the execution sequence of dependent scripts:

Input

```
useHead({
  script: [
    {
      key: 'jquery',
      src: '/js/jquery.js'
    },
    {
      key: 'plugin',
      src: '/js/jquery-plugin.js',
      tagPriority: 'after:script:jquery' // Ensure jQuery loads first
    },
    {
      key: 'app',
      src: '/js/app.js',
      tagPriority: 'after:script:plugin' // Load app.js last
    }
  ]
})
```

## [Best Practices](#best-practices)

- Use meaningful keys that describe the tag's purpose
- Keep dependencies simple - avoid complex chains
- Consider using numeric priorities for critical tags
- Document your tag ordering strategy for your team

During hydration (SSR or page switches), tags may not reorder to avoid content flashing. The plugin respects this behavior.

## [Related](#related)

- [Tag Positions](https://unhead.unjs.io/docs/head/guides/core-concepts/positions) - Control tag ordering

[Edit this page](https://github.com/unjs/unhead/edit/main/docs/head/1.guides/plugins/alias-sorting.md)

[Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/1.guides/plugins/alias-sorting.md)

Did this page help you?

[Template Params Dynamic placeholders like %s and %siteName in head tags. Define site name, separator, and custom variables for consistent branding.](https://unhead.unjs.io/docs/head/guides/plugins/template-params) [Canonical Plugin Auto-generate canonical URLs and convert relative paths to absolute. Required for og:image, twitter:image, and SEO canonical links.](https://unhead.unjs.io/docs/head/guides/plugins/canonical)

On this page

- [What Is Alias Sorting?](#what-is-alias-sorting)
- [Why Use Aliases Instead of Numbers?](#why-use-aliases-instead-of-numbers)
- [How Do I Set Up Alias Sorting?](#how-do-i-set-up-alias-sorting)
- [How Do I Use Alias Sorting?](#how-do-i-use-alias-sorting)
- [Common Use Cases](#common-use-cases)
- [Best Practices](#best-practices)
- [Related](#related)

[GitHub](https://github.com/unjs/unhead) [ Discord](https://discord.com/invite/275MBUBvgP)

[ /llms.txt](https://unhead.unjs.io/llms.txt)

[Part of the UnJS ecosystem](https://unjs.io/)

### Head Management

- [Getting Started](https://unhead.unjs.io/docs/nuxt/head/guides/get-started/overview)
- [useHead](https://unhead.unjs.io/docs/nuxt/head/api/composables/use-head)
- [useSeoMeta](https://unhead.unjs.io/docs/nuxt/head/api/composables/use-seo-meta)
- [useHeadSafe](https://unhead.unjs.io/docs/nuxt/head/api/composables/use-head-safe)
- [useScript](https://unhead.unjs.io/docs/nuxt/head/api/composables/use-script)

### Schema.org

- [Getting Started](https://unhead.unjs.io/docs/nuxt/schema-org/guides/get-started/overview)
- [useSchemaOrg](https://unhead.unjs.io/docs/nuxt/schema-org/api/composables/use-schema-org)
- [Nodes](https://unhead.unjs.io/docs/nuxt/schema-org/guides/core-concepts/nodes)
- [Recipes](https://unhead.unjs.io/docs/nuxt/schema-org/guides/recipes/identity)

### Guides

- [Titles](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/titles)
- [Streaming SSR](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/streaming)
- [DOM Events](https://unhead.unjs.io/docs/nuxt/head/guides/core-concepts/dom-event-handling)
- [Plugins](https://unhead.unjs.io/docs/nuxt/head/guides/plugins/template-params)

### Tools

- [Meta Tag Generator](https://unhead.unjs.io/tools/meta-tag-generator)
- [OG Image Generator](https://unhead.unjs.io/tools/og-image-generator)
- [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator)
- [Capo.js Analyzer](https://unhead.unjs.io/tools/capo-analyzer)

### Articles

- [What is Capo.js?](https://unhead.unjs.io/learn/guides/what-is-capo)

### Research

- [State of <head> in 2026](https://unhead.unjs.io/learn/research/state-of-head-2026)
- [Streaming Head Performance](https://unhead.unjs.io/learn/research/streaming-head-performance)
- [Capo.js Performance Research](https://unhead.unjs.io/learn/research/capo-performance-research)

Copyright © 2025-2026 Harlan Wilton - [MIT License](https://github.com/unjs/unhead/blob/main/license)