DEV Community: QuickGradeCalc

Build a Keyboard-Driven Test Grader in Plain JavaScript

QuickGradeCalc — Sat, 17 Oct 2026 20:50:21 +0000

Grading a stack of tests is repetitive: count the misses, convert to a percentage, look up the letter, repeat. It's a nice small project because the logic is tiny, but a few details decide whether the tool feels good to use.

In this tutorial we'll build a grader in one HTML file with no dependencies. You set the question count once, tap a button (or press a key) for each wrong answer, and the percentage and letter update instantly.

1. The grading function

Keep the logic in one pure function, separate from the page:

const DEFAULT_SCALE = [
  { letter: 'A', min: 90 },
  { letter: 'B', min: 80 },
  { letter: 'C', min: 70 },
  { letter: 'D', min: 60 },
];

function gradeTest(total, wrong, scale = DEFAULT_SCALE) {
  if (!Number.isInteger(total) || total <= 0) {
    throw new RangeError('total must be a positive integer');
  }
  const missed = Math.min(Math.max(wrong, 0), total);
  const correct = total - missed;
  const sorted = [...scale].sort((a, b) => b.min - a.min);
  const hit = sorted.find(({ min }) => correct * 100 >= min * total);
  return {
    correct,
    percent: (correct * 100) / total,
    letter: hit ? hit.letter : 'F',
  };
}

Three choices are worth explaining:

Clamping. wrong is forced into the range 0..total, so a stray extra tap can never produce a negative score.
Cross-multiplying. Instead of testing correct / total * 100 >= min, the code tests correct * 100 >= min * total. That stays in integers, so a score sitting exactly on a cutoff is never decided by floating-point rounding. When I compared the two approaches for tests of up to 200 questions, the division version happened to agree everywhere, but the integer version means you never have to wonder. It works as long as your cutoffs are whole numbers.
Sorting the scale. Sorting from the highest cutoff down means a custom scale works even if someone enters it out of order.

2. The page

<label>Questions <input id="total" type="number" min="1" value="20"></label>
<p class="result"><span id="percent">100%</span> <span id="letter">A</span></p>
<p>Wrong: <span id="wrong">0</span></p>

<div class="controls">
  <button id="add">+1 wrong</button>
  <button id="undo">Undo</button>
  <button id="reset">Reset</button>
  <p><small>Keys: W +1 wrong · E undo · R reset</small></p>
</div>

<h2>Quick chart</h2>
<table id="chart"></table>

The state is one number, wrong. The total comes from the input, so there is nothing else to keep in sync.

3. Rendering

const $ = (id) => document.getElementById(id);
let wrong = 0;

function render() {
  const total = Math.max(1, Math.floor(Number($('total').value) || 1));
  wrong = Math.min(wrong, total);
  const { percent, letter } = gradeTest(total, wrong);

  $('wrong').textContent = wrong;
  $('percent').textContent = `${Math.round(percent * 10) / 10}%`;
  $('letter').textContent = letter;

  $('chart').innerHTML =
    '<tr><th>Wrong</th><th>Score</th><th>Letter</th></tr>' +
    Array.from({ length: total + 1 }, (_, w) => {
      const r = gradeTest(total, w);
      return `<tr><td>${w}</td><td>${Math.round(r.percent * 10) / 10}%</td><td>${r.letter}</td></tr>`;
    }).join('');
}

If someone clears the input or types a decimal, the Math.max(1, Math.floor(...)) line turns it into a valid integer, so gradeTest never throws. The table doubles as a quick chart of every possible score.

4. Buttons and keyboard shortcuts

const add = () => { wrong++; render(); };
const undo = () => { wrong = Math.max(0, wrong - 1); render(); };
const reset = () => { wrong = 0; render(); };

$('add').addEventListener('click', add);
$('undo').addEventListener('click', undo);
$('reset').addEventListener('click', reset);
$('total').addEventListener('input', render);

document.addEventListener('keydown', (e) => {
  if (e.ctrlKey || e.metaKey || e.altKey) return;        // keep Ctrl+R, Cmd+W, etc.
  if (e.target instanceof HTMLInputElement) return;      // don't hijack typing
  ({ w: add, e: undo, r: reset })[e.key.toLowerCase()]?.();
});

render();

Single-letter shortcuts have two classic bugs, and both are handled above:

Browser shortcuts. R on its own should reset the count, but Ctrl+R or Cmd+R should still reload the page. Returning early when a modifier key is held fixes that.
Typing in the input. Without the instanceof HTMLInputElement check, typing a w into a field would trigger a tap.

The lookup object { w: add, e: undo, r: reset } keeps the key map in one place, and the ?.() quietly ignores every other key.

5. Make the chart printable

A printed chart beside the papers beats flipping back to the screen. A few lines of CSS hide the buttons when printing:

@media print {
  .controls { display: none; }
}

6. Test the logic

Because gradeTest is a pure function, tests are trivial. Move it to grade.js with export, then run this with Node:

import assert from 'node:assert/strict';
import { gradeTest } from './grade.js';

assert.equal(gradeTest(30, 3).letter, 'A');         // 27/30 = 90%, exactly on the cutoff
assert.equal(gradeTest(20, 3).percent, 85);
assert.equal(gradeTest(25, 5).letter, 'B');         // 80%, exactly on the cutoff
assert.equal(gradeTest(10, 15).letter, 'F');        // clamped to 0 correct
assert.equal(gradeTest(3, 1).letter, 'D');          // 66.67%
console.log('all good');

Always test the exact cutoff values, since those are where grading tools go wrong.

Where to take it next

Let users edit the cutoffs and pass the result into gradeTest as scale.
Support tests where questions have different point values (switch to points earned over points possible).
Save the question count and scale in localStorage so they survive a refresh.

Everything runs in the browser, with no backend, so student scores never leave the page.

This tutorial is a simplified version of the idea behind QuickGradeCalc, a free grading tool I run for teachers. If you'd rather use a finished version than build one, it works the same way: set the question count, then tap +1 wrong.

What would you add first: custom cutoffs, per-question points, or saved settings?

The Math Behind Weighted Grades, in Next.js

QuickGradeCalc — Thu, 15 Oct 2026 22:29:17 +0000

I built a free grade calculator with Next.js, and the part that surprised me most was how little of it is framework code. Nearly all of the logic is plain math that fits in three small functions. Here they are, with the edge cases that tripped me up, and a privacy-first component that uses them.

1. Weighted grade

Courses usually weight categories (homework 20%, exams 40%, and so on). The trick is to divide by the weight you have actually completed, not by 100, so a half-finished course still gives a sensible "grade so far".

// lib/grades.js
// items: [{ score: 92, weight: 20 }, { score: 84, weight: 30 }]
export function weightedGrade(items) {
  const totalWeight = items.reduce((sum, i) => sum + i.weight, 0);
  if (totalWeight <= 0) return null;

  const earned = items.reduce((sum, i) => sum + i.score * i.weight, 0);
  return earned / totalWeight;
}

Example: a 90 worth 25% and an 80 worth 25% give (90 * 25 + 80 * 25) / 50 = 85. Only half the course is graded, so 85 is the grade so far, not a prediction.

2. The score you need on a final

This is the question students ask most. If the final is worth weight percent and you want target overall:

// weight is a percentage, like 30
export function neededScore(current, target, weight) {
  if (!(weight > 0 && weight <= 100)) return null;

  const w = weight / 100;
  return (target - current * (1 - w)) / w;
}

Example: a current grade of 83, a target of 85, and a final worth 30%:

(85 - 83 * 0.70) / 0.30 = 89.67

The student needs about 89.7% on the final. If the result is over 100, the target can't be reached through the final alone, and the UI should say that plainly instead of showing a number like 112%.

3. Quick grading for a stack of tests

For a teacher, counting wrong answers is faster than counting right ones:

export function percentFromWrong(totalQuestions, wrong) {
  if (!(totalQuestions > 0)) return null;

  const correct = Math.max(totalQuestions - wrong, 0);
  return (correct / totalQuestions) * 100;
}

On a 30-question test with 4 wrong, that returns 86.67.

Test the math, not the UI

Pure functions are easy to test. A few lines with Vitest or Jest catch most bugs:

import { describe, it, expect } from "vitest";
import { weightedGrade, neededScore, percentFromWrong } from "./grades";

describe("grades", () => {
  it("handles a partly graded course", () => {
    expect(
      weightedGrade([
        { score: 90, weight: 25 },
        { score: 80, weight: 25 },
      ])
    ).toBe(85);
  });

  it("finds the score needed on a final", () => {
    expect(neededScore(83, 85, 30)).toBeCloseTo(89.67, 2);
  });

  it("rejects invalid weights", () => {
    expect(neededScore(83, 85, 0)).toBeNull();
  });

  it("converts wrong answers to a percentage", () => {
    expect(percentFromWrong(30, 4)).toBeCloseTo(86.67, 2);
  });
});

A privacy-first component

A grade calculator handles personal data, so I made it work entirely in the browser: no network requests, no cookies, no localStorage, and no values in the URL. Inputs are validated before any math runs.

// components/FinalCalculator.jsx
"use client";

import { useState } from "react";
import { neededScore } from "@/lib/grades";

// Turns raw text into a safe number, or null if it isn't usable.
function parseValue(raw, min, max) {
  const cleaned = String(raw).replace(",", ".").trim();
  if (cleaned === "" || !/^\d{0,3}(\.\d{0,2})?$/.test(cleaned)) return null;
  const n = Number(cleaned);
  if (!Number.isFinite(n) || n < min || n > max) return null;
  return n;
}

function Field({ label, value, onChange }) {
  return (
    <label style={{ display: "block", marginBottom: 12 }}>
      {label}
      <input
        type="text"
        inputMode="decimal"
        autoComplete="off"
        spellCheck={false}
        value={value}
        onChange={(e) => onChange(e.target.value)}
        style={{ display: "block", width: "100%", padding: 8 }}
      />
    </label>
  );
}

export default function FinalCalculator() {
  const [current, setCurrent] = useState("");
  const [target, setTarget] = useState("");
  const [weight, setWeight] = useState("");

  const c = parseValue(current, 0, 200);
  const t = parseValue(target, 0, 200);
  const w = parseValue(weight, 1, 100);

  let message = "Enter your numbers to see the result.";
  if (c !== null && t !== null && w !== null) {
    const result = neededScore(c, t, w);
    if (result === null || !Number.isFinite(result)) {
      message = "Please check your numbers.";
    } else if (result > 100) {
      message = "That target can't be reached with this exam alone.";
    } else {
      message = `You need about ${Math.max(result, 0).toFixed(1)}% on the final.`;
    }
  }

  return (
    <section>
      <h2>Final exam calculator</h2>

      {/* No <form> and no submit, so values never leave this component. */}
      <Field label="Current grade (%)" value={current} onChange={setCurrent} />
      <Field label="Target grade (%)" value={target} onChange={setTarget} />
      <Field label="Exam weight (%)" value={weight} onChange={setWeight} />

      <p aria-live="polite">{message}</p>

      <button
        type="button"
        onClick={() => {
          setCurrent("");
          setTarget("");
          setWeight("");
        }}
      >
        Clear
      </button>
    </section>
  );
}

To stop the page from sending data anywhere else, I also added a strict Content Security Policy in next.config.js:

// next.config.js
const csp = [
  "default-src 'self'",
  "script-src 'self' 'unsafe-inline'",
  "style-src 'self' 'unsafe-inline'",
  "img-src 'self' data:",
  "connect-src 'self'", // blocks sending data to other sites
  "frame-ancestors 'none'",
  "base-uri 'self'",
  "form-action 'self'",
].join("; ");

module.exports = {
  poweredByHeader: false,
  async headers() {
    return [
      {
        source: "/(.*)",
        headers: [
          { key: "Content-Security-Policy", value: csp },
          { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
          { key: "X-Content-Type-Options", value: "nosniff" },
        ],
      },
    ];
  },
};

Note that in development mode Next.js also needs 'unsafe-eval' in script-src for hot reload, and any analytics or ad script has to be added to the policy.

What I learned

Keep the math in pure functions. They are easy to test, and the component stays thin.
Be deliberate about edge cases. Zero weights, scores over 100, empty inputs, and NaN all show up with real users.
Treat grades as personal data. Doing everything client-side means there is nothing to leak.
One page per search intent. Separate pages for "percentage to letter grade" and "final grade" were clearer for users and for search engines than one page that did everything.

If you want to see it working, you can try the calculator at QuickGradeCalc. I'd also like to hear how grading works where you live (GPA scales, letter bands, and so on), since it varies a lot between countries.

What would you add to a tool like this?