Categories

Categories allow you to group related domains that share the same schedule and unblock delay. Instead of repeating configuration for each domain, define it once in the category.

Basic Structure

{
  "categories": [
    {
      "id": "social-media",
      "description": "Social networks",
      "unblock_delay": "4h",
      "schedule": {
        "available_hours": [
          {
            "days": ["saturday", "sunday"],
            "time_ranges": [{"start": "10:00", "end": "22:00"}]
          }
        ]
      },
      "domains": ["facebook.com", "instagram.com", "tiktok.com"]
    }
  ]
}

Category Fields

id (required)

Unique identifier for the category.

Rules:

Must start with a lowercase letter
Only lowercase letters, numbers, and hyphens allowed
Maximum 50 characters

{"id": "social-media"}

Valid examples:

social-media
gambling
streaming-video
work-tools

Invalid examples:

Social-Media (uppercase)
123social (starts with number)
-social (starts with hyphen)
social_media (underscore not allowed)

domains (required)

Array of domains in this category.

{
  "id": "streaming",
  "domains": ["netflix.com", "hbomax.com", "disneyplus.com"]
}

Notes:

Each domain inherits the category’s schedule and unblock_delay
A domain can only belong to one category
A domain cannot be in both a category and the blocklist

description (optional)

Human-readable description of the category.

{
  "id": "gambling",
  "description": "Betting and casino sites - always blocked"
}

unblock_delay (optional)

Friction before manual unblocking. Default is "0".

{
  "id": "social-media",
  "unblock_delay": "4h"
}

Supports flexible duration format:

Format	Description
`"0"`	Instant unblock
`"30m"`	30 minutes
`"2h"`	2 hours
`"1d"`	1 day
`"never"`	Cannot unblock

See Unblock Delay for details.

schedule (optional)

When domains in this category are accessible. Default is null (always blocked).

{
  "id": "streaming",
  "schedule": {
    "available_hours": [
      {
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
        "time_ranges": [{"start": "19:00", "end": "23:00"}]
      },
      {
        "days": ["saturday", "sunday"],
        "time_ranges": [{"start": "10:00", "end": "23:00"}]
      }
    ]
  }
}

See Schedules for details.

Common Patterns

{
  "id": "social-media",
  "description": "Social networks - evenings and weekends",
  "unblock_delay": "4h",
  "schedule": {
    "available_hours": [
      {
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
        "time_ranges": [
          {"start": "12:00", "end": "13:00"},
          {"start": "18:00", "end": "22:00"}
        ]
      },
      {
        "days": ["saturday", "sunday"],
        "time_ranges": [{"start": "10:00", "end": "23:00"}]
      }
    ]
  },
  "domains": ["instagram.com", "tiktok.com", "snapchat.com", "twitter.com"]
}

Gambling (Never Unblockable)

{
  "id": "gambling",
  "description": "Betting and casino sites - permanently blocked",
  "unblock_delay": "never",
  "schedule": null,
  "domains": ["stake.com", "caliente.mx", "bet365.com", "draftkings.com"]
}

Streaming (Evenings Only)

{
  "id": "streaming",
  "description": "Video streaming - evenings and weekends",
  "unblock_delay": "2h",
  "schedule": {
    "available_hours": [
      {
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
        "time_ranges": [{"start": "19:00", "end": "23:00"}]
      },
      {
        "days": ["saturday", "sunday"],
        "time_ranges": [{"start": "10:00", "end": "23:00"}]
      }
    ]
  },
  "domains": ["netflix.com", "hbomax.com", "disneyplus.com", "primevideo.com"]
}

Gaming (Weekends Only)

{
  "id": "gaming",
  "description": "Gaming platforms - weekends only",
  "unblock_delay": "4h",
  "schedule": {
    "available_hours": [
      {
        "days": ["saturday", "sunday"],
        "time_ranges": [{"start": "10:00", "end": "22:00"}]
      }
    ]
  },
  "domains": ["store.steampowered.com", "epicgames.com", "gog.com"]
}

Categories vs Blocklist

Feature	Categories	Blocklist
Grouping	Multiple domains share settings	Each domain configured individually
Best for	Related domains with same schedule	Unique schedules per domain
Configuration	Define once, apply to all	Repeat for each domain

When to Use Categories

Multiple domains need the same schedule
You want to organize domains logically
Easier maintenance of related domains

When to Use Blocklist

Each domain needs unique settings
One-off domains that don’t fit a group
Legacy configurations

Managing Categories

nextdns-blocker category list

Output:

Categories (3)

ID              Domains   Delay    Description
──────────────────────────────────────────────────────────────
social-media    4         4h       Social networks
gambling        3         never    Betting and casino sites
streaming       4         2h       Video streaming

Show Category Details

nextdns-blocker category show social-media

Output:

Category: social-media
━━━━━━━━━━━━━━━━━━━━━━

Description: Social networks
Unblock Delay: 4h

Schedule:
  Mon-Fri: 12:00-13:00, 18:00-22:00
  Sat-Sun: 10:00-23:00

Domains (4):
  - instagram.com
  - tiktok.com
  - snapchat.com
  - twitter.com

Create Category

nextdns-blocker category create gaming -d "Gaming platforms"
nextdns-blocker category create gambling --delay never

Add Domain to Category

nextdns-blocker category add social-media reddit.com

Remove Domain from Category

nextdns-blocker category remove social-media reddit.com

Delete Category

nextdns-blocker category delete gaming

See category command for full reference.

Validation Rules

Unique Domain Placement

A domain cannot appear in:

Multiple categories
Both a category and the blocklist

// ❌ Invalid - domain in two categories
{
  "categories": [
    {"id": "social", "domains": ["twitter.com"]},
    {"id": "news", "domains": ["twitter.com"]}
  ]
}

Unique Category IDs

Each category must have a unique ID:

// ❌ Invalid - duplicate ID
{
  "categories": [
    {"id": "social", "domains": ["facebook.com"]},
    {"id": "social", "domains": ["twitter.com"]}
  ]
}

Validate Configuration

nextdns-blocker config validate

Subdomain Handling

Automatic Inheritance

Blocking amazon.com in a category blocks:

amazon.com
www.amazon.com
smile.amazon.com
*.amazon.com

Subdomain Exceptions

Use allowlist for exceptions:

{
  "categories": [
    {
      "id": "shopping",
      "domains": ["amazon.com"]
    }
  ],
  "allowlist": [
    {"domain": "aws.amazon.com", "description": "Work resource"}
  ]
}

Result:

amazon.com → Blocked (per schedule)
www.amazon.com → Blocked
aws.amazon.com → Always allowed

Sync Behavior

When sync runs:

Categories are expanded into individual domain entries
Each domain inherits the category’s schedule and unblock_delay
Domains are evaluated against NextDNS denylist

# Preview sync
nextdns-blocker config push --dry-run

# Force sync
nextdns-blocker config push

Migration from Blocklist

To convert blocklist entries to a category:

Before (blocklist):

{
  "blocklist": [
    {"domain": "facebook.com", "unblock_delay": "4h", "schedule": {...}},
    {"domain": "twitter.com", "unblock_delay": "4h", "schedule": {...}},
    {"domain": "instagram.com", "unblock_delay": "4h", "schedule": {...}}
  ]
}

After (category):

{
  "categories": [
    {
      "id": "social-media",
      "unblock_delay": "4h",
      "schedule": {...},
      "domains": ["facebook.com", "twitter.com", "instagram.com"]
    }
  ],
  "blocklist": []
}

Complete Example

{
  "version": "1.0",
  "settings": {
    "timezone": "America/New_York"
  },
  "categories": [
    {
      "id": "social-media",
      "description": "Social networks and messaging",
      "unblock_delay": "4h",
      "schedule": {
        "available_hours": [
          {
            "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
            "time_ranges": [
              {"start": "12:00", "end": "13:00"},
              {"start": "18:00", "end": "22:00"}
            ]
          },
          {
            "days": ["saturday", "sunday"],
            "time_ranges": [{"start": "10:00", "end": "23:00"}]
          }
        ]
      },
      "domains": ["instagram.com", "tiktok.com", "snapchat.com"]
    },
    {
      "id": "gambling",
      "description": "Gambling and betting - never unblockable",
      "unblock_delay": "never",
      "schedule": null,
      "domains": ["stake.com", "caliente.mx", "bet365.com"]
    },
    {
      "id": "streaming",
      "description": "Video streaming - evenings only",
      "unblock_delay": "2h",
      "schedule": {
        "available_hours": [
          {
            "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
            "time_ranges": [{"start": "19:00", "end": "23:00"}]
          },
          {
            "days": ["saturday", "sunday"],
            "time_ranges": [{"start": "10:00", "end": "23:00"}]
          }
        ]
      },
      "domains": ["netflix.com", "hbomax.com", "disneyplus.com"]
    }
  ],
  "blocklist": [],
  "allowlist": [
    {"domain": "aws.amazon.com", "description": "Work resource"}
  ]
}