Formatters

ESLint formatters control the appearance of linting results in the CLI. ESLint comes with several built-in formatters and supports third-party formatters as well.

Using Formatters

Specify a formatter using the --format or -f flag:

npx eslint --format <formatter-name> file.js
npx eslint -f <formatter-name> file.js

The default formatter is stylish, which provides human-readable output with colors.

Built-in Formatters

ESLint includes four built-in formatters:

stylish

Default formatterHuman-readable with colors and context

json

JSON outputFor programmatic processing

json-with-metadata

JSON + metadataIncludes rule metadata

html

HTML reportVisual browser-based report

stylish (Default)

The stylish formatter provides clean, readable output with color coding:

npx eslint --format stylish file.js

Example Output
Features
Usage

file.js
10  error    'addOne' is defined but never used  no-unused-vars
9   error    Use the isNaN function to compare   use-isnan
16  error    Unexpected space before unary       space-unary-ops
20  warning  Missing semicolon                   semi
7   error    Function 'addOne' expected return  consistent-return

✖ 5 problems (4 errors, 1 warning)
error and 1 warning potentially fixable with the `--fix` option.

# Default (no flag needed)
npx eslint file.js

# Explicit
npx eslint --format stylish file.js

Colors can be controlled with --color and --no-color flags, or via environment variables like FORCE_COLOR, NO_COLOR, or NODE_DISABLE_COLORS.

json

Outputs JSON-serialized results for programmatic processing:

npx eslint --format json file.js

Structure
Properties
Usage

[
  {
    "filePath": "/path/to/file.js",
    "messages": [
      {
        "ruleId": "no-unused-vars",
        "severity": 2,
        "message": "'addOne' is defined but never used.",
        "line": 1,
        "column": 10,
        "messageId": "unusedVar",
        "endLine": 1,
        "endColumn": 16,
        "suggestions": []
      }
    ],
    "suppressedMessages": [],
    "errorCount": 5,
    "fatalErrorCount": 0,
    "warningCount": 4,
    "fixableErrorCount": 1,
    "fixableWarningCount": 4,
    "source": "function addOne(i) {...}"
  }
]

File-level:

filePath - Absolute path to the file
messages - Array of violations
errorCount - Number of errors
warningCount - Number of warnings
fixableErrorCount - Fixable errors
fixableWarningCount - Fixable warnings
source - File source code

Message-level:

ruleId - Rule identifier
severity - 1 (warn) or 2 (error)
message - Violation message
line, column - Start position
endLine, endColumn - End position
fix - Auto-fix information (if available)

# Output to console
npx eslint --format json file.js

# Save to file
npx eslint --format json file.js > results.json

# Use with jq
npx eslint --format json file.js | jq '.[] | .errorCount'

Use the JSON formatter when:

Building CI/CD integrations
Creating custom reporting tools
Processing results programmatically
Storing results in databases

json-with-metadata

Extends the JSON formatter with rule metadata:

npx eslint --format json-with-metadata file.js

Structure
Metadata Fields
Usage

{
  "results": [
    {
      "filePath": "/path/to/file.js",
      "messages": [...],
      "errorCount": 5,
      "warningCount": 4
    }
  ],
  "metadata": {
    "cwd": "/path/to/project",
    "rulesMeta": {
      "no-unused-vars": {
        "type": "problem",
        "docs": {
          "description": "Disallow unused variables",
          "recommended": true,
          "url": "https://eslint.org/docs/rules/no-unused-vars"
        },
        "hasSuggestions": true,
        "schema": [...]
      }
    }
  }
}

rulesMeta contains:

type - Rule type (problem, suggestion, layout)
docs - Documentation information
- description - Rule description
- recommended - If rule is recommended
- url - Documentation URL
hasSuggestions - If rule provides suggestions
fixable - If rule is auto-fixable
schema - Rule options schema
messages - Rule message templates

npx eslint --format json-with-metadata file.js

Useful for:

Generating documentation
Building rule explorers
Creating rich IDE integrations
Understanding rule capabilities

html

Generates an interactive HTML report:

npx eslint --format html file.js > report.html

Features
Usage
Best For

Interactive HTML report with:

Color-coded violations
Sortable columns
Filterable results
File grouping
Rule descriptions
Click-to-expand details
Summary statistics
Professional styling

# Generate HTML report
npx eslint --format html src/ > report.html

# Open in browser
npx eslint --format html src/ > report.html && open report.html

# Multiple directories
npx eslint --format html src/ lib/ tests/ > report.html

The HTML formatter is designed for viewing in a browser and includes all necessary CSS and JavaScript inline.

Saving Output to File

Shell Redirection
--output-file Flag

# Save JSON results
npx eslint --format json file.js > results.json

# Save HTML report
npx eslint --format html src/ > report.html

# Append to existing file
npx eslint --format json file.js >> all-results.json

# Using -o flag
npx eslint -f json -o results.json file.js

# Using full flag name
npx eslint --format html --output-file report.html src/

Custom Formatters

You can create and use custom formatters:

Local Custom Formatter

Create formatter file

my-formatter.js

module.exports = function(results, context) {
  // results: array of linting results
  // context: formatter context object
  
  let output = "";
  let totalErrors = 0;
  let totalWarnings = 0;
  
  results.forEach(result => {
    const { filePath, messages } = result;
    
    if (messages.length > 0) {
      output += `\n${filePath}\n`;
      
      messages.forEach(message => {
        const { line, column, severity, message: msg, ruleId } = message;
        const type = severity === 2 ? "ERROR" : "WARNING";
        
        output += `  ${line}:${column} ${type} ${msg} (${ruleId})\n`;
        
        if (severity === 2) totalErrors++;
        else totalWarnings++;
      });
    }
  });
  
  output += `\n${totalErrors} errors, ${totalWarnings} warnings\n`;
  
  return output;
};

Use the formatter

npx eslint --format ./my-formatter.js file.js

NPM Package Formatter

Install formatter

npm install --save-dev eslint-formatter-pretty
# or
npm install --save-dev eslint-formatter-table

Use the formatter

# With prefix
npx eslint --format eslint-formatter-pretty file.js

# Without prefix (ESLint adds it)
npx eslint --format pretty file.js

ESLint automatically adds the eslint-formatter- prefix if not present.

Formatter Context

Formatters receive two arguments:

module.exports = function(results, context) {
  // results: array of linting results
  // context: formatter context
};

Results Array

[
  {
    filePath: "/absolute/path/to/file.js",
    messages: [
      {
        ruleId: "no-unused-vars",
        severity: 2,  // 1 = warn, 2 = error
        message: "'x' is defined but never used.",
        line: 1,
        column: 5,
        nodeType: "Identifier",
        messageId: "unusedVar",
        endLine: 1,
        endColumn: 6,
        fix: {  // Only if fixable
          range: [0, 10],
          text: ""
        },
        suggestions: [  // Only if has suggestions
          {
            desc: "Remove unused variable",
            fix: { range: [0, 10], text: "" }
          }
        ]
      }
    ],
    suppressedMessages: [],  // Suppressed violations
    errorCount: 1,
    fatalErrorCount: 0,
    warningCount: 0,
    fixableErrorCount: 1,
    fixableWarningCount: 0,
    source: "const x = 5;\n",  // File source code
    usedDeprecatedRules: []  // Deprecated rules used
  }
]

Context Object

{
  cwd: "/absolute/path/to/project",
  maxWarningsExceeded: {
    maxWarnings: 10,
    foundWarnings: 15
  },
  rulesMeta: {  // Only in json-with-metadata
    "no-unused-vars": {
      type: "problem",
      docs: { /* ... */ },
      hasSuggestions: true
    }
  }
}

Comparing Formatters

CLI Development
CI/CD
Reports
Analysis

Best: stylish

npx eslint --format stylish src/

Human-readable
Color-coded
Quick scan of issues
Shows line numbers

Best: json

npx eslint --format json src/ > results.json

Programmatically processable
Can be stored/archived
Integration-friendly
Parseable by tools

Best: html

npx eslint --format html src/ > report.html

Visual presentation
Shareable
Non-technical friendly
Interactive

Best: json-with-metadata

npx eslint --format json-with-metadata src/ > analysis.json

Complete information
Rule metadata included
Documentation generation
Advanced tooling

Popular Third-Party Formatters

eslint-formatter-pretty

Beautiful formatter with colors and context:

npm install --save-dev eslint-formatter-pretty
npx eslint --format pretty src/

Features:

Syntax highlighting
Code context
File hyperlinks (VS Code, WebStorm)
Summary statistics

eslint-formatter-table

Table-based output:

npm install --save-dev eslint-formatter-table
npx eslint --format table src/

Features:

Tabular layout
Column alignment
Clear separation
Sortable data

eslint-formatter-gitlab

GitLab Code Quality format:

npm install --save-dev eslint-formatter-gitlab
npx eslint --format gitlab src/ > gl-code-quality-report.json

Use for:

GitLab CI/CD integration
Code Quality widgets
Merge request reports

eslint-formatter-codeframe

Shows code context with pointers:

npm install --save-dev eslint-formatter-codeframe
npx eslint --format codeframe src/

Features:

Code snippets
Error pointers
Detailed context
Multiple lines

Example Workflow

Development
CI/CD
Git Hooks
Package Scripts

# Quick checks during development
npx eslint src/

# Or with watch mode
npx eslint-watch src/

#!/bin/bash

# Run ESLint and save results
npx eslint --format json src/ > eslint-results.json

# Generate HTML report for artifacts
npx eslint --format html src/ > eslint-report.html

# Check exit code
if [ $? -ne 0 ]; then
  echo "ESLint found errors"
  exit 1
fi

# .husky/pre-commit

# Lint staged files
npx lint-staged

# Or directly
npx eslint --format stylish $(git diff --cached --name-only --diff-filter=ACM | grep '\.js$')

package.json

{
  "scripts": {
    "lint": "eslint src/",
    "lint:fix": "eslint --fix src/",
    "lint:report": "eslint --format html src/ > reports/eslint.html",
    "lint:json": "eslint --format json src/ > reports/eslint.json",
    "lint:ci": "eslint --format json --output-file reports/eslint.json src/"
  }
}

Best Practices

Choose the Right Formatter

Development: stylish for readability
CI/CD: json for processing
Reports: html for stakeholders
Analysis: json-with-metadata for tooling

Save Important Results

# Save to file for later review
npx eslint --format json src/ > results-$(date +%Y%m%d).json

# Archive HTML reports
npx eslint --format html src/ > reports/week-$(date +%U).html

Combine Formatters

Output to console AND file:

# Using tee (Unix)
npx eslint --format json src/ | tee results.json

# Or run twice
npx eslint src/ && npx eslint --format json src/ > results.json

Format Warnings Separately

# Only show errors
npx eslint --quiet src/

# Then check warnings separately
npx eslint src/

Command Line

CLI options including —format

Integrations

Editor and build tool integrations

Configuration

Configure ESLint for your project

Core Concepts

Understanding ESLint fundamentals

Get Started

Using ESLint

Extending ESLint

Guides

Formatters

Formatters

Using Formatters

Built-in Formatters

stylish

json

json-with-metadata

html

stylish (Default)

json

json-with-metadata

html

Saving Output to File

Custom Formatters

Local Custom Formatter

NPM Package Formatter

Formatter Context

Results Array

Context Object

Comparing Formatters

Popular Third-Party Formatters

Example Workflow

Best Practices

Command Line

Integrations

Configuration

Core Concepts

Get Started

Using ESLint

Extending ESLint

Guides

​Formatters

​Using Formatters

​Built-in Formatters

stylish

json

json-with-metadata

html

​stylish (Default)

​json

​json-with-metadata

​html

​Saving Output to File

​Custom Formatters

​Local Custom Formatter

​NPM Package Formatter

​Formatter Context

​Results Array

​Context Object

​Comparing Formatters

​Popular Third-Party Formatters

​Example Workflow

​Best Practices

​Related Resources

Command Line

Integrations

Configuration

Core Concepts

Formatters

Using Formatters

Built-in Formatters

stylish (Default)

json

json-with-metadata

html

Saving Output to File

Custom Formatters

Local Custom Formatter

NPM Package Formatter

Formatter Context

Results Array

Context Object

Comparing Formatters

Popular Third-Party Formatters

Example Workflow

Best Practices

Related Resources