Web Development - freeCodeCamp.org

How to Build More Accessible Websites with WCAG 2.2

Aiyedogbon Abraham — Tue, 18 Aug 2026 16:33:33 +0000

A website can look polished, work perfectly with a mouse, and still be difficult for some people to use.

A form might use colour as the only indication that something went wrong. A sticky header might completely cover the element that currently has keyboard focus. A login form might prevent users from pasting a password from their password manager. Or a custom button might work when clicked with a mouse but do nothing when someone uses a keyboard.

These are development decisions, not problems that only appear during an accessibility audit.

The Web Content Accessibility Guidelines (WCAG) provide a common standard for identifying and reducing many of these barriers. WCAG 2.2 is the latest WCAG 2 Recommendation, and the World Wide Web Consortium (W3C) advises developers and organisations to use WCAG 2.2 whenever possible.

This article focuses on the WCAG 2.2 Level A and AA requirements that frequently affect frontend development. The aim is to show how accessibility requirements connect to frontend development decisions.

What Is WCAG 2.2?
How WCAG Conformance Works
How the Four WCAG Principles Work
How to Start with Semantic HTML
How to Write Useful Text Alternatives for Images
How to Handle Colour, Contrast, Text Resizing, and Reflow
How to Make an Interface Work with a Keyboard
How to Keep Keyboard Focus Visible
How to Design Pointer Targets and Dragging Interactions
How to Build More Accessible Forms
How to Avoid Redundant Entry
How to Keep Help Consistent
How WCAG 2.2 Affects Authentication
How to Use ARIA Without Replacing HTML
How to Make Dynamic Status Messages Accessible
How to Test Your Website for Accessibility
Conclusion

What Is WCAG 2.2?

WCAG stands for Web Content Accessibility Guidelines. W3C develops the standard to describe how web content can be made more accessible to people with disabilities.

WCAG 2.2 organises its requirements into principles, guidelines, and testable success criteria. The success criteria are technology-independent, which is important because WCAG doesn't exist specifically for HTML, React, WordPress, or any other implementation technology.

Consider this hierarchy:

Principle: Operable

    Guideline 2.1: Keyboard Accessible

        Success Criterion 2.1.1: Keyboard

The principle gives you the broad accessibility objective. The guideline narrows that objective, while the success criterion provides the testable requirement.

W3C also publishes resources such as Understanding WCAG 2.2, How to Meet WCAG 2.2, and Techniques for WCAG 2.2. These resources explain the success criteria and provide implementation approaches, examples, and known failures. They're informative rather than part of the normative WCAG requirements.

A W3C technique can show one recognised way to satisfy a criterion, but WCAG generally doesn't require you to use that exact technique. Another implementation can also be valid if it meets the actual success criterion.

How WCAG Conformance Works

WCAG defines three conformance levels: A, AA, and AAA.

The levels build on one another. A page can't claim Level AA conformance by satisfying only the criteria labelled AA. It must satisfy all applicable Level A and Level AA success criteria. Level AAA similarly includes A, AA, and AAA requirements.

This distinction is important because accessibility discussions sometimes reduce WCAG to individual checks.

You might fix the keyboard interaction on a menu, add alternatives to your images, and correct several contrast problems. Those are useful accessibility improvements, but they don't automatically make the entire website "WCAG AA compliant".

WCAG conformance applies to complete web pages. When a process requires several pages to complete, such as a checkout process, all pages in that process must conform at the claimed level.

The examples in this article therefore demonstrate ways to address particular accessibility requirements. They don't constitute a conformance claim for an entire application.

How the Four WCAG Principles Work

WCAG groups its guidelines under four principles commonly remembered with the acronym POUR: Perceivable, Operable, Understandable, and Robust.

Perceivable means users need to be able to perceive the information you provide. Text alternatives, captions, contrast, and adaptable layouts fall under this principle.

Operable concerns how people interact with the interface. Keyboard operation, focus behaviour, navigation, pointer interactions, and timing are examples.

Understandable deals with whether users can understand the information and the way the interface behaves. Form instructions, useful error messages, predictable interfaces, and accessible authentication are relevant here.

Robust concerns whether browsers and assistive technologies can correctly interpret the content. Semantic HTML, accessible names, roles, values, and states are central to this principle.

These categories are useful, but accessibility problems rarely respect the boundary between HTML, CSS, and JavaScript.

A custom dropdown, for example, might need semantic information in the markup, visible focus styling in CSS, and correct keyboard behaviour in JavaScript.

Accessibility therefore works best when it forms part of the implementation itself rather than becoming a separate task at the end of development.

How to Start with Semantic HTML

One of the most useful accessibility decisions happens before you write any ARIA: choosing the correct HTML element.

Consider this:

Submit

A mouse user may be able to click the element, but a div doesn't automatically behave like a button.

Compare it with this:

The native button already communicates its role to the browser and provides the expected keyboard behaviour.

This relates to Success Criterion 4.1.2 Name, Role, Value, which requires user interface components to expose information such as their name and role programmatically. W3C notes that standard controls already provide much of this information when developers use them according to their specification.

The practical implication is simple: don't recreate browser behaviour unless you need to.

How Semantic HTML Communicates Page Structure

Semantic HTML also helps expose relationships between parts of a page.

You could build a page like this:


  ...



  ...



  Account Settings
  ...

The classes may create the visual layout you want, but they don't necessarily communicate the same structure programmatically.

A more meaningful structure could be:


  ...



  ...



  Account Settings
  ...

Success Criterion 1.3.1 Info and Relationships requires structure and relationships communicated visually to also be programmatically determinable or available in text. Semantic markup can provide this information without requiring developers to recreate it with additional accessibility attributes.

This doesn't mean that using

, and

automatically makes a page accessible. It means you're giving the browser more accurate information about what the content represents.

Repeated page navigation creates another issue.

If a page has a large navigation menu, a keyboard user may otherwise need to move through those links every time before reaching the main content.

A skip link provides another path:


  Skip to main content



  ...



  ...



  ...

You can position the link outside the normal view until it receives keyboard focus:

.skip-link {
  position: absolute;
  top: -4rem;
  left: 1rem;
}

.skip-link:focus {
  top: 1rem;
}

This is one recognised way to support Success Criterion 2.4.1 Bypass Blocks, which requires a mechanism for bypassing blocks of repeated content. WCAG requires the outcome rather than this exact CSS implementation.

The broader principle is worth keeping: use HTML's existing semantics before adding custom semantics yourself.

How to Write Useful Text Alternatives for Images

Adding alt text is one of the best-known accessibility practices, but the rule is often oversimplified.

Success Criterion 1.1.1 Non-text Content requires non-text content to have a text alternative that serves an equivalent purpose, subject to several exceptions. Decorative content, for example, should be implemented so assistive technologies can ignore it.

The important word is purpose.

Consider this image:

The alternative tells the user that the page contains a chart. It doesn't communicate anything the chart actually tells a sighted user.

If the main message is the change in revenue, an alternative could be:

That doesn't mean every chart can be reduced to one sentence.

If the chart contains several data series or detailed values that readers need, you may also need a nearby explanation, accessible table, or another way of communicating the underlying information.

The alternative should reflect what the image contributes in its context.

How to Handle Decorative Images

A decorative image serves a different purpose.

Consider a visual divider:

The empty alt value indicates that the image doesn't contribute information that needs to be announced.

A missing alt attribute and alt="" are therefore not interchangeable. The empty alternative is an intentional decision.

How to Handle Icons Inside Controls

Now consider a search button containing a magnifying-glass SVG.

The relevant information isn't that the user is looking at a magnifying glass. The important information is that the control starts a search.

The button receives the accessible name Search, while the SVG itself doesn't add duplicate information.

When deciding what alternative to provide, ask a more useful question than "What does this image look like?"

Ask: What information or function would the user lose if they couldn't perceive this image visually? That distinction matters when implementing accessibility.

How to Handle Colour, Contrast, Text Resizing, and Reflow

Accessibility also affects ordinary CSS decisions.

A layout may look correct at your preferred viewport size and still become difficult to use when somebody changes the way content is displayed.

How to Avoid Relying Only on Colour

Imagine a form that changes an input border from grey to red when validation fails:

.input {
  border: 1px solid #777;
}

.input.error {
  border-color: red;
}

The colour communicates that something changed, but a user needs to perceive that colour difference to understand the state.

Success Criterion 1.4.1 Use of Color requires colour not to be the only visual means used to convey information, indicate an action, prompt a response, or distinguish a visual element.

An improved implementation can combine styling with actual text:

Email address




  Enter an email address in the format name@example.com.

You can still use a red border. It just shouldn't carry the message alone.

How to Check Text Contrast

Success Criterion 1.4.3 Contrast (Minimum) requires regular text to have a contrast ratio of at least 4.5:1. Qualifying large-scale text has a minimum ratio of 3:1, subject to the criterion's exceptions.

Don't judge contrast only by looking at the colours. Two colours can look sufficiently different on your display while still falling below the required ratio. Use a contrast-testing tool as part of your design and development process.

How Non-Text Contrast Differs from Text Contrast

Success Criterion 1.4.11 Non-text Contrast deals with visual information needed to identify interface components, states, and meaningful graphical objects. The required ratio is generally 3:1 against adjacent colours, subject to the criterion's scope and exceptions.

This can affect things such as custom form controls, meaningful icons, component boundaries, selected states, and graphical information.

Passing the text contrast requirement therefore doesn't automatically mean the rest of the interface has sufficient contrast.

How to Support Text resizing

Success Criterion 1.4.4 Resize Text requires text, with specified exceptions, to be resizable up to 200% without loss of content or functionality.

Fixed dimensions often expose problems here.

Consider:

.card {
  height: 180px;
  overflow: hidden;
}

If text grows beyond the space the developer assumed it would need, some content can disappear.

Where the design doesn't genuinely require a fixed height, allowing the component to grow is safer:

.card {
  min-height: 180px;
}

This doesn't prove that the component passes the criterion. You still need to resize the text and inspect the result.

The CSS simply removes one common source of failure.

How to Design for Reflow

Success Criterion 1.4.10 Reflow addresses the ability to use content at narrow equivalent dimensions without losing information or functionality or requiring prohibited two-dimensional scrolling.

For vertically scrolling content, the criterion uses a width equivalent to 320 CSS pixels. Certain content, such as some maps and data tables, may genuinely require two-dimensional layout and falls under the criterion's exceptions.

A flexible layout can help ordinary content adapt:

.settings-grid {
  display: grid;
  grid-template-columns:
    repeat(auto-fit, minmax(min(100%, 18rem), 1fr));
  gap: 1rem;
}

As space decreases, the cards move onto new rows rather than forcing the entire page to remain wide.

Responsive design helps here, but "responsive" and "accessible" aren't synonyms.

A responsive page can still hide controls, clip text, overlap content, or remove functionality at high zoom. Test the behaviour rather than assuming a media query solves the accessibility requirement.

How to Make an Interface Work with a Keyboard

One of the simplest manual accessibility tests is to put the mouse aside and use the application with a keyboard.

Success Criterion 2.1.1 Keyboard requires functionality to be operable through a keyboard interface except where the underlying function genuinely depends on the path of the user's movement. WCAG doesn't prevent the interface from also supporting mouse, touch, voice, or other forms of input.

Let's return to our custom control:

Save

Making the div look like a button doesn't give it button behaviour.

You could begin rebuilding that behaviour yourself:


  Save

But now your JavaScript must also provide the appropriate keyboard interaction.

In most cases, this is unnecessary:

Native controls reduce the amount of interaction behaviour you need to reproduce.

W3C's ARIA Authoring Practices Guide makes this distinction explicit: ARIA roles don't cause browsers to add the keyboard behaviour that comes with native HTML controls. If you create a custom ARIA widget, you're responsible for implementing those interactions.

How to Check for Keyboard Traps

Success Criterion 2.1.2 No Keyboard Trap addresses situations where keyboard focus enters a component but can't leave through a keyboard interface.

This is particularly relevant to custom editors, dialogs, embedded widgets, and other complex controls.

Keyboard testing should go beyond asking whether you can press Tab until an element receives focus.

Try to complete the actual task. If you open a dialog, can you use its controls and close it? If you enter a custom widget, can you leave it? If a menu opens, can you operate it using its expected keyboard pattern?

Keyboard accessibility concerns the whole interaction, not simply whether an element appears in the tab order.

How to Keep Keyboard Focus Visible

Keyboard navigation becomes difficult when users can't tell which element currently has focus.

This CSS is therefore risky:

*:focus {
  outline: none;
}

It removes the browser's default focus indication without providing an alternative.

Success Criterion 2.4.3 Focus Order requires a keyboard-operable interface to provide a mode in which the keyboard focus indicator is visible.

If the default outline doesn't fit your design, replace it with another visible focus treatment rather than simply removing it:

button:focus-visible,
a:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: 3px solid currentColor;
  outline-offset: 3px;
}

This is an example, not a guarantee of conformance. Your chosen indicator still needs to remain visible against the colours surrounding the component.

How WCAG 2.2 Deals with Obscured Focus

WCAG 2.2 added Success Criterion 2.4.11 Focus Not Obscured (Minimum) at Level AA.

When a user interface component receives keyboard focus, author-created content must not completely hide it. The Level AA criterion requires at least part of the focused component to remain visible.

A sticky header illustrates the problem:

.site-header {
  position: sticky;
  top: 0;
  height: 5rem;
}

There's nothing inherently inaccessible about a sticky header. The problem occurs if the page scrolls a focused link or control entirely behind that header.

CSS such as this can help when scroll positioning is involved:

html {
  scroll-padding-top: 6rem;
}

But don't treat it as a complete fix.

Test the real keyboard interaction because cookie notices, fixed bottom navigation, chat windows, sticky toolbars, and other overlays can create similar problems.

The important requirement is the outcome: when focus moves, the user should still be able to see the focused component.

How to Design Pointer Targets and Dragging Interactions

Keyboard support doesn't cover every interaction barrier.

WCAG 2.2 introduced additional requirements that are particularly relevant to touchscreens, drag-and-drop interfaces, and compact controls.

How to Provide an Alternative to Dragging

Imagine a task board where users reorder cards only by dragging them.

Dragging may work well for many users, but it depends on pressing a pointer, moving it while maintaining that interaction, and releasing it in the correct place.

Success Criterion 2.5.7 Dragging Movements requires functionality that uses a dragging movement to also be achievable without dragging through a single-pointer operation, unless dragging is essential to the function.

You can keep drag-and-drop while providing another control:


  Prepare monthly report

The exact reorder logic depends on your application.

The important part is that the user has another pointer-based way to perform the same function without having to drag the card.

WCAG isn't saying "don't use drag-and-drop". It's saying that dragging shouldn't unnecessarily become the only route to the functionality.

How to Think About Target Size

Success Criterion 2.5.8 Target Size (Minimum) is another WCAG 2.2 Level AA addition.

The criterion uses a minimum target size of 24 by 24 CSS pixels or a defined spacing alternative and contains several exceptions. It therefore should not be simplified to "every clickable element must always be at least 24 pixels wide and high".

For an isolated icon button, you can choose to provide an even larger target:

.icon-button {
  min-width: 2.75rem;
  min-height: 2.75rem;

  display: inline-grid;
  place-items: center;
}

At a typical root font size, this deliberately creates a target larger than the WCAG minimum.

The visible icon can remain smaller:

The size of the icon and the size of the interactive target are not the same thing.

That distinction is useful when designing dense interfaces.

How to Keep the Accessible Name Aligned with the Visible Label

Success Criterion 2.5.3 Label in Name concerns controls that have a visible text label.

The accessible name should contain the visible label text. This is particularly important for users who operate interfaces using speech and refer to controls by the words they can see.

Avoid this:

The visible label is Search, but the accessible name is Find products.

In this case, the simplest version is better:

If additional accessible context is genuinely necessary, retain the visible wording:

Before adding an aria-label, check whether the visible text already gives the control an adequate accessible name.

How to Build More Accessible Forms

Forms combine several areas of accessibility: structure, instructions, errors, input purpose, and status changes.

Start with the field itself.

How to Label Form Controls

This pattern is common:

The placeholder provides a visual hint, but it's not a good replacement for a proper label.

Use:


  Email address

Success Criterion 3.3.2 Labels or Instructions requires labels or instructions when content requires user input.

The for and id values also create a programmatic relationship between the label and the field.

How to Identify Common Input Purposes

Success Criterion 1.3.5 Identify Input Purpose applies to fields collecting certain types of information about the user. Their purpose needs to be programmatically determinable when the technology supports it.

HTML's autocomplete tokens help communicate common purposes:


  Full name





  Email address

This also allows browsers and other tools to provide useful input assistance.

How to Write Useful Validation Errors

Now consider an error message:

Invalid input.

The message tells the user almost nothing: Which input is invalid? What's wrong with it? What needs to change?

Success Criterion 3.3.1 Error Identification requires an automatically detected input error to identify the item in error and describe the error in text.

An implementation might look like this:


  Email address





  Enter an email address in the format name@example.com.

aria-invalid="true" exposes the invalid state. aria-describedby associates the explanation with the field.

More importantly, the message tells the user what needs correcting.

Success Criterion 3.3.3 Error Suggestion goes further at Level AA. When the system detects an input error and knows how it can be corrected, it should provide an appropriate suggestion unless doing so would compromise the security or purpose of the content.

The aim isn't to make every error message long. The aim is to make it actionable.

How to Avoid Redundant Entry

Consider a checkout process.

The user enters a delivery address on one step. The next step asks them to type exactly the same address again for billing.

WCAG 2.2 introduced Success Criterion 3.3.7 Redundant Entry at Level A.

When information previously entered by or provided to the user is required again during the same process, the information must generally be auto-populated or available for the user to select. The criterion includes exceptions where re-entry is essential, necessary for security, or where the previous information is no longer valid.

A checkout might offer:


  
  Use my delivery address as my billing address

Notice that the requirement concerns information within the same process. It doesn't mean every website has to remember every value a user entered during earlier visits.

This criterion also shows why accessibility extends beyond screen-reader support.

Reducing unnecessary repetition can lower the cognitive and interaction effort required to complete a task.

How to Keep Help Consistent

WCAG 2.2 also added Success Criterion 3.2.6 Consistent Help at Level A.

If certain help mechanisms appear repeatedly across a set of pages, they need to appear in the same relative order unless the user initiates a change. These mechanisms can include human contact details, contact mechanisms, self-help options, and automated contact mechanisms.

Suppose your account pages all provide a support link in the header:


  Acme

  
    
  

  Support

Do not move that support mechanism unpredictably between otherwise related pages.

A key nuance is that WCAG 2.2 does not require every website to introduce one of these help mechanisms.

The criterion applies when qualifying help is already available and repeated across multiple pages in the same set.

The development implication is therefore mostly about consistency.

If users learn where help appears on one page, avoid making them search for it again on the next.

How WCAG 2.2 Affects Authentication

Authentication is another area that changed in WCAG 2.2.

Consider a login form that deliberately blocks paste:

passwordInput.addEventListener("paste", (event) => {
  event.preventDefault();
});

That may appear to encourage users to type a password manually, but it can also interfere with mechanisms that reduce the need to remember or transcribe credentials.

Success Criterion 3.3.8 Accessible Authentication (Minimum) addresses authentication steps that require cognitive function tests.

The Level AA requirement allows such tests when an accepted alternative or assistance mechanism is available. W3C specifically identifies password-manager support and copy-and-paste as mechanisms that can reduce the cognitive burden involved in authentication.

A conventional login form can allow these tools to work:


  Email address





  Password

It would be inaccurate to simplify this criterion to "WCAG 2.2 prohibits passwords". It does not.

A password is a cognitive function test, but the criterion permits it when the user has a mechanism that assists with completing that test, such as a password manager that can fill the field.

The same reasoning becomes relevant to multi-factor authentication.

If a process requires a user to read a code on one device and manually transcribe it to another, consider whether the authentication flow offers a path that avoids that cognitive burden. W3C's guidance explicitly discusses authentication processes with several steps and the need for an accessible path through them.

This is a good example of why the exact criterion matters more than a simplified accessibility checklist.

How to Use ARIA Without Replacing HTML

ARIA stands for Accessible Rich Internet Applications.

It provides roles, states, and properties that help web applications communicate information that may not otherwise be available to assistive technologies.

ARIA is useful. It's also easy to misuse.

Consider this example:


  Place order

The role tells accessibility APIs that the element represents a button. It doesn't make the element behave like a button.

W3C ARIA Authoring Practices Guide describes an ARIA role as a promise. When you use role="button", you take responsibility for providing the expected keyboard and interaction behaviour yourself. ARIA doesn't cause the browser to add that behaviour automatically.

Where a native HTML element already exists, prefer it:

How ARIA Can Communicate State

ARIA becomes useful when HTML alone doesn't communicate enough about a component's current state.

Consider a disclosure control:




  Profile
  Security

You can keep aria-expanded in sync with the visible state:

const trigger = document.querySelector(
  "#account-options-trigger"
);

const panel = document.querySelector(
  "#account-options"
);

trigger.addEventListener("click", () => {
  const isExpanded =
    trigger.getAttribute("aria-expanded") === "true";

  trigger.setAttribute(
    "aria-expanded",
    String(!isExpanded)
  );

  panel.hidden = isExpanded;
});

The JavaScript does two related things.

It changes whether the panel is hidden, and it updates the accessibility state exposed by the trigger.

If the panel opens visually but aria-expanded remains false, the interface now communicates two conflicting states.

This illustrates a useful ARIA rule: ARIA state must describe the interface that actually exists.

For more complex patterns such as dialogs, comboboxes, tabs, menus, and grids, the W3C ARIA Authoring Practices Guide provides documented interaction patterns and examples. W3C also makes clear that APG is implementation guidance rather than a normative accessibility standard.

How to Make Dynamic Status Messages Accessible

Modern interfaces frequently update without loading a new page.

A user might save a profile and see:

Your settings were saved.

Or run a search and see:

18 results found.

A sighted user can often notice these updates without moving away from the current control.

Assistive technology also needs a programmatic way to identify relevant status messages.

Success Criterion 4.1.3 Status Messages requires qualifying status messages to be programmatically determinable so assistive technologies can present them without requiring the message itself to receive focus.

For a routine save confirmation, you can use role="status":

Then update its content:

const saveButton = document.querySelector(
  "#save-settings"
);

const saveStatus = document.querySelector(
  "#save-status"
);

saveButton.addEventListener("click", () => {
  saveStatus.textContent =
    "Your settings were saved.";
});

The browser can expose that status change to supporting assistive technologies without moving keyboard focus away from the Save button.

Not every dynamic DOM change is a status message.

WCAG defines the term more narrowly. It includes information about the result or success of an action, an application's waiting state, the progress of a process, or the existence of errors when that update doesn't itself constitute a change of context.

Don't make every changing piece of content a live announcement. An excessively chatty interface can create a different usability problem.

Use status semantics for information users need to receive while continuing their current task.

How to Test Your Website for Accessibility

Accessibility testing works best as a combination of methods.

WCAG itself is designed to support testing through both automated tools and human evaluation. An automated scanner can identify many technical problems, but it can't reliably judge every accessibility requirement or determine whether an entire user journey makes sense.

How to Start with Automated Testing

Automated tools are useful for repeatable technical checks.

They can identify many problems involving accessible names, some contrast failures, invalid ARIA usage, form relationships, and other machine-detectable conditions.

The limitation appears when correctness depends on meaning.

A tool can tell you that an image has an alt attribute. It can't always determine whether the text accurately communicates the purpose of the image.

Automation should therefore start the evaluation, not end it.

How to Perform Keyboard Testing

Open the page, put the mouse aside, and try to complete an actual task using only your keyboard.

Start with Tab to move forwards through interactive elements and Shift + Tab to move backwards.

Use Enter and Space to activate controls where appropriate. Custom widgets may also use arrow keys or Escape depending on their interaction pattern. The ARIA Authoring Practices keyboard guidance documents expected behaviour for common widget patterns.

Don't simply press Tab a few times and stop.

For example, if you're testing a checkout flow:

Navigate to the basket.
Change a quantity.
Continue to checkout.
Move through the form.
Submit it.
Correct an error.
Complete the process.

As you do this, check whether you can reach and operate every required control, move away from every component, follow a sensible focus sequence, see where focus currently is, and avoid having focused content hidden by an overlay.

If something goes wrong, the relevant requirements include Success Criterion 2.1.1 Keyboard, Success Criterion 2.1.2 No Keyboard Trap, Success Criterion 2.4.3 Focus Order, Success Criterion 2.4.7 Focus Visible, and Success Criterion 2.4.11 Focus Not Obscured (Minimum).

How to Test Zoom, Resizing, and Reflow

You can perform a basic zoom test directly in your browser.

In most browsers:

use Ctrl + + on Windows or Linux
use Cmd + + on macOS
use Ctrl/Cmd + 0 to return to the default zoom

W3C's Zoom Easy Check suggests testing at 200%.

As you increase zoom, work through the page and look for:

clipped text
overlapping elements
controls that disappear
navigation that stops working
content hidden behind other content
horizontal scrolling across ordinary page content

Also use a narrow browser window or responsive browser tools to inspect how the content reflows.

This is to verify the behaviour discussed under Success Criterion 1.4.4 Resize Text and Success Criterion 1.4.10 Reflow.

How to Test Colour and Contrast

Use a contrast checker or the colour information available in your browser developer tools to measure foreground and background combinations.

Do this for ordinary text as well as important non-text elements such as custom control borders, icons, and state indicators.

Then test colour-dependent information separately.

For example, if an error field turns red, temporarily ignore the colour change and ask whether another visible indication still communicates the error.

These checks correspond to Success Criterion 1.4.1 Use of Color, Success Criterion 1.4.3 Contrast (Minimum), and Success Criterion 1.4.11 Non-text Contrast.

How to Test Forms Manually

Don't test a form only with valid information. You should deliberately make mistakes to test as many cases as possible.

Leave a required field empty. Enter an incorrectly formatted email address. Submit a value the form should reject.

Then check whether you can:

identify the field that has a problem
understand the error message
determine how to correct it
reach the error using the keyboard
correct the information and continue

Also inspect form controls in your browser developer tools to confirm that visible labels and descriptions are associated with the correct fields.

These tests help you verify Success Criterion 3.3.1 Error Identification, Success Criterion 3.3.2 Labels or Instructions, and Success Criterion 3.3.3 Error Suggestion.

How to Test Pointer and Dragging Interactions

If your interface contains drag-and-drop, complete the action normally first. Then try to perform the same function without dragging.

For example, if you can drag a task into a new position, check whether another pointer-operated control lets you move it as well.

That gives you a practical test for Success Criterion 2.5.7 Dragging Movements.

For small controls, use browser developer tools to inspect the rendered interactive area rather than judging only the visible icon.

Pay particular attention to close buttons, carousel controls, pagination items, icon buttons, and densely packed toolbars when checking Success Criterion 2.5.8 Target Size (Minimum).

How to Inspect the Accessibility Tree

Modern browser developer tools expose accessibility information associated with elements.

Inspect important controls and compare what the accessibility tree reports with what the interface shows.

A button might visually say Search while its accessible name says something completely different. A disclosure may look open while its aria-expanded state remains false.

Inspecting the accessibility tree helps expose these mismatches.

How to Test with Assistive Technology

When testing with a screen reader, focus on complete tasks.

For a form, navigate to the fields, identify their labels, enter incorrect information, submit it, locate and understand the errors, correct them, and confirm the successful state.

The question isn't simply:

Can the screen reader read this page?

The more useful question is:

Can the user complete the task and understand what happened?

Testing with disabled users can reveal additional usability barriers that automated and standards-based evaluation may not expose.

Conclusion

WCAG becomes easier to understand when you connect its requirements to normal development decisions. The important shift is to stop treating accessibility as a final audit. Build it into the interface while you build everything else.

How to Build a Browser-Based PDF to Grayscale Converter Using JavaScript

Bhavin Sheth — Fri, 14 Aug 2026 15:57:42 +0000

Many PDF documents contain colorful charts, presentations, marketing materials, scanned pages, or graphics that aren't always ideal for printing or archiving.

In some cases, converting a document to grayscale reduces distractions, creates printer-friendly versions, lowers printing costs, or prepares files for black-and-white publishing.

A PDF to Grayscale Converter automates this process. Instead of editing every page manually, users can upload a PDF, choose how the grayscale conversion should be applied, preview the results, and download a newly generated document, all from within the browser.

In this tutorial, you'll build a browser-based PDF to Grayscale Converter using JavaScript. Users will be able to upload a PDF, preview every page, adjust the grayscale intensity, choose between multiple conversion modes, select which pages to process, generate a grayscale PDF, preview the final result, rename the output file, and download it without uploading their document to an external server.

We'll use PDF.js to render PDF pages, the HTML Canvas API to manipulate image pixels, and PDF-lib to generate the final downloadable PDF.

By the end of this tutorial, you'll have a complete client-side PDF processing application similar to the one available on All In One Tools.

What This PDF to Grayscale Converter Does and How It Works
Project Setup
Libraries Used
Creating the HTML Layout
Uploading and Previewing PDFs
Building the Conversion Settings
Converting PDF Pages to Grayscale
Generating the Final PDF
Previewing the Result
Renaming and Downloading
Demo: How the PDF to Grayscale Converter Works
Performance Tips
Common Mistakes
Conclusion

What This PDF to Grayscale Converter Does and How It Works

A PDF to Grayscale Converter transforms colorful PDF pages into shades of gray while preserving the document's layout, page dimensions, text placement, and images. Instead of removing content, it recalculates the color of every pixel so the entire page appears in grayscale.

This is useful for creating printer-friendly documents, reducing color distractions, preparing files for monochrome printing, improving consistency across scanned documents, or producing black-and-white versions for review and archival purposes.

In this project, users can upload a PDF, browse through every page, adjust the grayscale intensity, choose between different conversion modes, decide whether all pages or only selected pages should be converted, generate a new grayscale PDF, preview the completed document, rename the output file, and download it directly from the browser.

Behind the scenes, PDF.js renders each PDF page onto an HTML canvas. Once the page has been rendered, JavaScript reads the RGB values for every pixel and calculates a grayscale value using a luminance formula. The updated pixels are written back to the canvas before PDF-lib assembles all processed pages into a brand-new PDF.

A typical pixel contains four values:

const pixel = {
    red: 180,
    green: 95,
    blue: 40,
    alpha: 255
};

To convert that pixel into grayscale, JavaScript calculates a single luminance value and applies it equally to the red, green, and blue channels.

const gray = 0.299 * red + 0.587 * green + 0.114 * blue;

The resulting pixel becomes:

pixel.red = gray;
pixel.green = gray;
pixel.blue = gray;

Repeating this process for every pixel on every selected page creates a new grayscale version of the original PDF while preserving the overall structure of the document.

Project Setup

Before writing the conversion logic, let's create a simple project structure.

We'll build everything using HTML, CSS, and JavaScript, together with PDF.js, the Canvas API, and PDF-lib.

Our project structure looks like this:

pdf-to-grayscale/
│── index.html
│── style.css
│── script.js
│── pdf.worker.min.js
│── assets/

Keeping the HTML, styling, and JavaScript separate makes the project easier to maintain as more PDF features are added.

Libraries Used

The PDF to Grayscale Converter relies on three browser technologies that work together to render PDF pages, process image pixels, and generate a new downloadable document.

PDF.js renders PDF pages directly inside the browser.

The HTML Canvas API provides access to every pixel so JavaScript can convert colors into grayscale.

PDF-lib creates the final PDF after all selected pages have been processed.

Include the required libraries before loading your application.

Configure the PDF.js worker.

pdfjsLib.GlobalWorkerOptions.workerSrc = "pdf.worker.min.js";

Using a worker allows PDF rendering to happen in the background without freezing the browser interface.

Creating the HTML Layout

The application is divided into four main sections:

Upload area
PDF preview
Conversion settings
Download section

Create the basic page structure.

Only the upload area is visible when the page first loads. The remaining sections appear after a PDF has been successfully opened.

Selecting the Main Elements

Store references to the elements that will be used throughout the application.

const uploadSection = document.getElementById("uploadSection");
const previewSection = document.getElementById("previewSection");
const settingsSection = document.getElementById("settingsSection");
const pdfCanvas = document.getElementById("pdfCanvas");

Using these references makes it easier to update the interface as users move through the conversion process.

Uploading and Previewing PDFs

The upload area accepts both drag-and-drop and manual file selection.

When a file is selected, first verify that it's a PDF.

async function uploadPdf(file) {
    if (!file || file.type !== "application/pdf") {
        alert("Please select a PDF file.");
        return;
    }

    await loadPdf(file);
}

Once validation succeeds, the document is loaded into memory for processing.

Loading the PDF

Convert the uploaded file into an ArrayBuffer before opening it with PDF.js.

async function loadPdf(file) {
    const bytes = await file.arrayBuffer();

    pdfDocument = await pdfjsLib.getDocument({
        data: bytes
    }).promise;

    currentPage = 1;
    renderPage(currentPage);
}

The loaded document is stored so every page can later be converted to grayscale.

Rendering PDF Pages

PDF.js renders one page at a time onto an HTML canvas.

Retrieve the page.

const page = await pdfDocument.getPage(currentPage);

Create the viewport.

const viewport = page.getViewport({
    scale: 1.5
});

Resize the canvas.

pdfCanvas.width = viewport.width;
pdfCanvas.height = viewport.height;

Render the page.

await page.render({
    canvasContext: pdfCanvas.getContext("2d"),
    viewport
}).promise;

Once rendering finishes, the selected page appears inside the preview area.

Navigating Between Pages

Most PDF documents contain multiple pages, so users need simple navigation controls.

Track the current page.

let currentPage = 1;
let pdfDocument = null;

Move to the previous page.

previousButton.addEventListener("click", async () => {
    if (currentPage > 1) {
        currentPage--;
        await renderPage(currentPage);
    }
});

Move to the next page.

nextButton.addEventListener("click", async () => {
    if (currentPage < pdfDocument.numPages) {
        currentPage++;
        await renderPage(currentPage);
    }
});

Update the page indicator.

pageCounter.textContent = `Page ${currentPage} of ${pdfDocument.numPages}`;

Users can now browse through the document before deciding how the grayscale conversion should be applied.

Building the Conversion Settings

After the PDF has been loaded and previewed, users can configure how the document should be converted to grayscale. The settings panel allows users to adjust the grayscale intensity, choose a conversion mode, decide which pages should be processed, and start the conversion.

Adjusting Grayscale Intensity

The intensity slider controls how strongly the grayscale effect is applied.

Lower values retain more of the original color, while higher values produce a true grayscale appearance.

Create the slider.

Read the selected value.

const intensity = Number(document.getElementById("grayIntensity").value);

The selected intensity will later be used when calculating the final grayscale color.

Choosing the Conversion Mode

The tool provides multiple grayscale modes for different use cases.

Create the radio buttons.


Standard Grayscale

Black & White

Soft Gray

Retrieve the selected mode.

const conversionMode = document.querySelector(
    'input[name="mode"]:checked'
).value;

Each mode uses a different algorithm when processing the canvas pixels.

Selecting the Pages

Users can convert either the entire document or only selected pages.

Create the page selection controls.


All Pages

Specific Pages

Read the selected option.

const applyMode = document.querySelector(
    'input[name="pages"]:checked'
).value;

Retrieve the custom page range.

const pageRange = document.getElementById("pageRange").value.trim();

When All Pages is selected, every page in the PDF is processed. Otherwise, only the pages specified by the user are converted.

Converting PDF Pages to Grayscale

Once the settings have been configured, users can begin the conversion.

Create the action button.

Start the conversion.

convertButton.addEventListener("click", async () => {
    await convertPdf();
});

Starting Over

Users can clear the current document and return the application to its initial state.

Create the reset button.

Reset the application.

resetTool.addEventListener("click", () => {
    location.reload();
});

This removes the current PDF and restores the default settings so another document can be processed.

Reading Canvas Pixels

After a page has been rendered, retrieve its pixel data.

const imageData = context.getImageData(
    0,
    0,
    canvas.width,
    canvas.height
);

The pixel information is stored in an array.

const pixels = imageData.data;

Each pixel contains four values:

Red
Green
Blue
Alpha

We'll update the RGB values while leaving the alpha channel unchanged.

Converting Colors to Grayscale

The standard grayscale algorithm calculates a luminance value using the red, green, and blue channels.

Loop through every pixel.

for (let i = 0; i < pixels.length; i += 4) {
    const gray =
        0.299 * pixels[i] +
        0.587 * pixels[i + 1] +
        0.114 * pixels[i + 2];

    pixels[i] = gray;
    pixels[i + 1] = gray;
    pixels[i + 2] = gray;
}

This formula produces a natural-looking grayscale image because it reflects how the human eye perceives brightness.

Applying the Selected Conversion Mode

Different conversion modes use different pixel calculations.

For example, the Black & White (Threshold) mode converts each pixel into either pure black or pure white.

const threshold = 128;
const color = gray >= threshold ? 255 : 0;
pixels[i] = color;
pixels[i + 1] = color;
pixels[i + 2] = color;

The Soft Gray mode blends the original color with the grayscale value to create a less aggressive effect.

const softGray =
    (gray * 0.6) +
    (pixels[i] * 0.4);

pixels[i] = softGray;
pixels[i + 1] = softGray;
pixels[i + 2] = softGray;

Once the selected mode has been applied, write the updated pixels back to the canvas.

context.putImageData(
    imageData,
    0,
    0
);

Processing the Selected Pages

Instead of processing the entire document every time, convert only the pages selected by the user.

Loop through the page range.

for (let page = startPage; page <= endPage; page++) {
    await processPage(page);
}

Each processed page is temporarily stored before the final PDF is created.

Generating the Final PDF

Create a new PDF document.

const outputPdf = await PDFLib.PDFDocument.create();

Convert the processed canvas into an image.

const imageBytes = await canvasToBytes(pdfCanvas);

Embed the image into the PDF.

const image = await outputPdf.embedPng(imageBytes);

Create a new page.

const page = outputPdf.addPage([
    image.width,
    image.height
]);

Draw the processed image.

page.drawImage(image, {
    x: 0,
    y: 0,
    width: image.width,
    height: image.height
});

Repeat this process for every selected page until the new grayscale document is complete.

Saving the Generated PDF

After all pages have been processed, save the completed document.

const pdfBytes = await outputPdf.save();

Create a downloadable PDF file.

generatedPdfBlob = new Blob([pdfBytes], {
    type: "application/pdf"
});

The grayscale PDF is now ready for preview, renaming, and downloading.

Previewing the Result

Before downloading the converted document, it's useful to let users review the final output. This allows them to verify that the selected pages have been converted correctly and that the grayscale appearance meets their expectations.

Load the generated PDF using PDF.js.

let finalPdf = null;

async function showResult() {
    const bytes = await generatedPdfBlob.arrayBuffer();

    finalPdf = await pdfjsLib.getDocument({
        data: bytes
    }).promise;

    renderResultPage(1);
}

Render the selected page.

async function renderResultPage(pageNumber) {
    const page = await finalPdf.getPage(pageNumber);

    const viewport = page.getViewport({
        scale: 1.5
    });

    resultCanvas.width = viewport.width;
    resultCanvas.height = viewport.height;

    await page.render({
        canvasContext: resultCanvas.getContext("2d"),
        viewport
    }).promise;
}

Users can browse through every converted page before downloading the PDF.

Renaming and Downloading

Before saving the converted PDF, users can provide a custom filename.

Create the filename input.

Retrieve the filename.

function getFilename() {
    let filename = outputFilename.value.trim();

    if (!filename) {
        filename = "grayscale-document.pdf";
    }

    if (!filename.toLowerCase().endsWith(".pdf")) {
        filename += ".pdf";
    }

    return filename;
}

Display information about the generated PDF.

pageCount.textContent = `${finalPdf.numPages} Pages`;
fileSize.textContent = formatFileSize(generatedPdfBlob.size);

Download the completed PDF.

downloadButton.addEventListener("click", () => {
    const url = URL.createObjectURL(generatedPdfBlob);

    const link = document.createElement("a");
    link.href = url;
    link.download = getFilename();
    link.click();

    URL.revokeObjectURL(url);
});

Everything happens locally inside the browser, allowing users to keep their documents private throughout the conversion process.

Demo: How the PDF to Grayscale Converter Works

Let's walk through the complete workflow.

Step 1: Upload the PDF

Users begin by dragging a PDF into the upload area or clicking Select PDF.

Step 2: Preview the Document

PDF.js renders the uploaded document page by page, allowing users to review the file before conversion.

Step 3: Configure the Conversion

Users adjust the grayscale intensity, choose a conversion mode, and decide whether to process all pages or only selected pages.

Step 4: Convert the PDF

Click Convert to Grayscale to begin processing the selected pages.

Step 5: Review the Converted Document

After processing is complete, the application displays a preview of the generated grayscale PDF.

Step 6: Rename and Download

Finally, users can rename the output file, review the page count and file size, and download the converted PDF.

Performance Tips

Large PDF files require more processing time because every page must be rendered and converted. Processing only the selected pages helps improve performance.

for (let page = startPage; page <= endPage; page++) {
    await processPage(page);
}

After downloading the file, release temporary resources to reduce memory usage.

URL.revokeObjectURL(downloadUrl);

These simple optimizations help keep the converter responsive when working with large multi-page PDF documents.

Common Mistakes

One common mistake is converting the same page multiple times without first rendering the original page again. Always start with the original PDF page before applying another grayscale conversion.

await renderPage(currentPage);

Another issue is allowing users to specify invalid page numbers.

if (pageNumber < 1 || pageNumber > pdfDocument.numPages) {
    return;
}

Finally, remember that higher output quality usually produces larger PDF files. Choosing the appropriate quality setting helps balance image clarity and file size.

Conclusion

In this tutorial, you built a browser-based PDF to Grayscale Converter using JavaScript.

You learned how to upload and preview PDF documents, render pages with PDF.js, convert colorful pages into grayscale using the Canvas API, process selected pages, generate a new PDF with PDF-lib, preview the completed document, rename the output file, and download it directly from the browser.

Because all processing happens locally, users can convert PDF documents to grayscale without uploading sensitive files to an external server.

You can explore the complete workflow using the PDF to Grayscale Converter.

From here, you can extend the project with additional features such as sepia conversion, brightness and contrast controls, custom grayscale presets, batch PDF processing, or support for additional image filters.

How to Create a Scalable KYC Onboarding Flow in React with Shadcn UI

Vaibhav Gupta — Thu, 13 Aug 2026 18:10:52 +0000

Every B2B SaaS product with a compliance requirement (like banking, lending, payroll, or crypto) hits the same wall early on: before you can let a business use your platform, you need to verify who they are.

That means collecting a business type, pulling in registration documents, and showing the user where their verification stands, all without making onboarding feel like a customs form.

This article breaks down a working three step KYC (Know Your Customer) flow built with Shadcn UI: a stepper for progress, a radio group for account type, a file upload zone for documents, and an alert for verification status. You'll see the actual component code, not a simplified stand-in, along with the reasoning behind each decision.

You can try the finished flow at onboarding-kyc-flow.vercel.app. Click through it once before reading on, as it makes the code below easier to follow. And it also comes in dark and light mode.

Prerequisites
What You're Building
Project Structure
Radix UI vs Base UI: Which Primitives this Flow Uses
Scaffolding the Flow with v0 and an MCP Server
Step 1: Account Type with a Radio Group
Step 2: Document Upload with Drag and Drop
Step 3: Verification Status with an Alert
Adding a Stepper to the Flow
Small Details that Make it Feel Finished
Accessibility notes
Key Concepts Recap
Conclusion
Resources

Prerequisites

Before working through this flow, you should be comfortable with React function components and hooks, specifically useState, useRef, and useEffect.

You should have:

A Next.js project with the App Router and shadcn/ui already initialized, since this article doesn't cover that initial setup.
A v0 account is optional. You can also use Bolt or Lovable, which support the same shadcn MCP prompt feature.

What You're Building

The flow has three steps:

Account type: The user picks Startup, Enterprise, or Government. This decision drives the rest of the experience. It's shown back to the user as a confirmation line, and would typically decide which workspace defaults get applied.
Document upload: The user drags in a business registration document, a tax return, or a company registry export, in PDF or CSV format.
Verification status: The user sees a live status: checking in progress, then either verified or an issue that needs attention.

Project Structure

The project is a standard Next.js app with shadcn/ui already initialized. Here's the top-level layout:

onboarding-kyc-flow/
├── .vercel/
├── app/
├── components/
├── lib/
├── public/
├── .env.development.local
├── .gitignore
├── components.json
├── next-env.d.ts
├── next.config.mjs
├── package.json
├── pnpm-lock.yaml
├── postcss.config.mjs
├── tsconfig.json
└── tsconfig.tsbuildinfo

components.json is the file the shadcn CLI reads to know where your components live and which style and primitives you're using. components/ holds the shared UI pieces (Alert, Badge, Button, Card, Progress, RadioGroup, Separator) that the flow is built from. lib/utils.ts provides the cn helper used throughout the flow to combine conditional class names. app/ holds the page itself, shown in full below.

Radix UI vs Base UI: Which Primitives this Flow Uses

Shadcn components aren't tied to one underlying primitive library. Most of the ecosystem defaults to Radix UI, but Base UI has become a solid alternative, and it's what this flow is built on.

The underlying primitive library can affect how a component behaves and how you work with it in your project. If you're pulling components from a set like Shadcn UI, check which primitive library it targets before mixing components from different sources.

Mixing Radix-based and Base UI-based components generally works, but it means using two different unstyled primitive libraries in the same project. You can compare Radix UI and Base UI here.

Scaffolding the Flow with v0 and an MCP Server

An MCP (Model Context Protocol) server exposes a component library to an AI coding assistant as a set of callable tools. Instead of the assistant guessing at component names and props from training data, it queries the server for the real, current API.

This matters here specifically, since there are now several shadcn-style component sets with similar names and different props.

The Shadcn Components library publishes an MCP server for its free set, connected to v0 by following its getting started guide. The video below covers the connection step by step. The same generated output can also be copied into Lovable or Bolt through their copy prompt feature, so the workflow isn't locked to one AI builder.

The prompt used to scaffold this flow looked like this:

Create an Enterprise SaaS Onboarding & KYC Flow. Use free components of the shadcn space MCP server: shadcn alert, shadcn radio group, shadcn stepper, shadcn file upload. Only use free components, not pro ones, and list which free component was used for each part.

Step 1: Account Type (stepper) - radio group for Startup, Enterprise, or Government

Step 2: Upload Documents (stepper) - file upload for a business registration document

Step 3: Verification (stepper) - alert showing verification status

This produces a working first draft fast. What follows is the result after cleaning that draft up: real state management, real validation, and states that a generated draft tends to skip.

Step 1: Account Type with a Radio Group

Account type is the first decision in the flow because it's the one most likely to affect what comes after it. Asking it early keeps the rest of the flow feeling relevant to the choice the user just made.

const tiers: { id: Tier; name: string; description: string; tag: string }[] = [
  { id: 'startup', name: 'Startup', description: 'For teams building and scaling fast', tag: 'Up to 25 seats' },
  { id: 'enterprise', name: 'Enterprise', description: 'For established teams with advanced needs', tag: 'Unlimited seats' },
  { id: 'government', name: 'Government', description: 'For public sector and regulated teams', tag: 'FedRAMP-ready' },
]

 setTier(value as Tier)} className="grid gap-3">
  
    Account type
    {tiers.map((item) => (
      
        
        
          
            {item.name}
            {item.id === 'enterprise' && Recommended}
          
          {item.description}
          {item.tag}
        
      
    ))}

Two things worth noticing here. The tier data lives in a plain array outside the component, so adding a fourth tier later is a one-line change, not a markup change. And the fieldset with a visually hidden (sr-only) legend groups the three options as one related choice for screen readers. Sighted users never see it, since the card title above already states "Choose your account type" visually.

This step uses a shadcn radio group rather than a select or checkboxes, since account type is a single, mutually exclusive choice, and a radio group is the only one of the three that makes both the options and the current selection visible at a glance.

Live Preview:

Step 2: Document Upload with Drag and Drop

The upload zone needs to handle three states cleanly: nothing selected yet, a file selected and ready, and a rejected file with a specific reason why.

function FileUpload({ file, onFile, onRemove, error }: {
  file: File | null
  onFile: (file: File) => void
  onRemove: () => void
  error: string
}) {
  const inputRef = useRef(null)
  const [dragging, setDragging] = useState(false)

  const accept = (candidate: File) => {
    if (candidate.type !== 'application/pdf' && candidate.type !== 'text/csv' && !candidate.name.toLowerCase().endsWith('.csv')) {
      return 'Upload a PDF or CSV file only.'
    }
    if (candidate.size > 10 * 1024 * 1024) {
      return 'Files must be smaller than 10 MB.'
    }
    onFile(candidate)
    return ''
  }

  return (
    
      {!file ? (
        
      ) : (
        
          
            
          
          
            {file.name}
            {(file.size / 1024 / 1024).toFixed(2)} MB · Ready to verify
          
          Uploaded
          
        
      )}
      {error && (
        
          
          Unsupported document
          {error}
        
      )}
    
  )
}

The accept function is the whole validation layer, and it runs from two different places: the change handler on the hidden file input, and the drop handler on the drag zone.

Both paths call the same function, so a file dragged in gets the same validation checks as a file selected by clicking browse. It ensures that only PDF or CSV files are allowed, regardless of how the file is added.

This is where shadcn file upload earns its place over a plain : the drag zone, the selected state, and the rejected state are all handled as one component instead of three separate pieces wired together by hand.

Live Preview:

Step 3: Verification Status with an Alert

Verification isn't instant, so the interface needs to say clearly what's happening and what happens next, rather than showing a spinner with no explanation.

{verified ? (
  
    
    Verification complete
    
      Your {selectedTier.name.toLowerCase()} workspace is ready to configure.
    
  
) : (
  <>
    
      
      Verification in progress
      
        This usually takes a few moments. You can keep this tab open while we finish.
      
    
    
      
        Checking business registry
        {checking ? '68%' : '100%'}
      
      
      
         Matching company details and tax identifiers
      
    
  
)}

Pairing the shadcn alert with a progress bar does two jobs at once: the alert states the current status in words, while the progress bar gives a rough sense of how much is left, without promising a specific time. Neither one alone tells the full story, the alert alone feels static, and a progress bar alone doesn't explain what's actually being checked.

Worth adding here, and easy to skip when a demo only shows the success path: a mismatch state, where the tax ID on the document doesn't match the company registry, deserves its own alert with a clear next step: contact support or re-upload a corrected document. It's not shown above, since the flow currently resolves to either checking or verified, but it's the state a production version of this flow would hit the most.

Live Preview:

Adding a Stepper to the Flow

The stepper is the visual anchor of the whole flow. It's the piece that tells the user how much is left before the checking and account-type-selecting are done.

function Stepper({ current }: { current: Step }) {
  return (
    
      {steps.map((step, index) => (
        
          
             step.number
                  ? 'border-primary bg-primary text-primary-foreground'
                  : current === step.number
                  ? 'border-primary bg-primary/10 text-primary'
                  : 'border-border bg-background text-muted-foreground'
              )}
              aria-current={current === step.number ? 'step' : undefined}
            >
              {current > step.number ?  : step.number}
            
            
              = step.number ? 'text-foreground' : 'text-muted-foreground')}>
                {step.label}
              
              {step.caption}
            
          
          {index < steps.length - 1 && (
             step.number ? 'bg-primary' : 'bg-border')} />
          )}
        
      ))}
    
  )
}

The current > step.number check keeps the entire stepper in sync with a single comparison. It determines the circle’s fill color, decides when the step number should be replaced by a checkmark, and controls whether the connecting line to the next step is filled.

This is important because the stepper only needs one piece of state, step, from the parent component. It doesn’t need to know why the user is on step 2, it only needs to know which step is currently active and update its visual state accordingly.

The "continue" logic that actually advances step lives outside the stepper itself:

const continueStep = () => {
  if (step === 1) setStep(2)
  else if (step === 2 && file) {
    setStep(3)
    setChecking(true)
    window.setTimeout(() => {
      setChecking(false)
      setVerified(true)
    }, 1400)
  }
}

Keeping this in the page component, not inside the shadcn stepper itself, is what keeps the stepper reusable. It only renders progress. Whether the user is allowed to move forward, a file is required on step 2, or whether nothing is required on step 1, is a decision for the flow around it to make.

Small Details that Make it Feel Finished

A few things in this build are easy to skip but change how the flow feels in practice:

A dark mode toggle in the header, wired to a darkMode state that toggles a class on document.documentElement. It's small, but it means the flow doesn't fight a user's system theme preference.
A security note in the sidebar, stating documents are encrypted and deleted after verification. This is copy, not code, but it answers the question a corporate user is quietest about and most worried by: what happens to the file after I upload it.
A "Selected" confirmation line under the radio group, restating the chosen tier in plain text. A small detail, but it removes any doubt about what was actually selected before moving on.

If you're looking to wrap a flow like this inside a full application shell, with navigation and a dashboard around it, the Shadcn Dashboard starter uses the same component set. It's a reasonable base to extend from rather than building a shell from scratch.

Live Preview:

https://onboarding-kyc-flow.vercel.app/

This project is open source, and you can easily download the zip and if you like. Please consider giving it a star.

Github Repo

Accessibility notes

The stepper's nav element has an aria-label, and the current step carries aria-current="step", so assistive technology can identify progress without relying on visual position alone.
The radio group sits inside a fieldset with a screen-reader-only legend, grouping the three account types as one decision.
Icons throughout (Check, AlertCircle, UploadCloud, and so on) carry aria-hidden="true", since they're decorative next to text that already states the same information. This stops screen readers from announcing redundant icon labels.
The remove-file button has an explicit aria-label, since its visible content is an icon only, with no text.

Key Concepts Recap

Account type comes first because it's the one decision most likely to affect the rest of the flow, and it's kept in state at the page level, not inside the radio group itself.
File validation runs in a shared function used by both the drag-and-drop path and the click-to-browse path, so both paths apply the same PDF/CSV validation.
Verification status is communicated with both words (the alert) and a rough sense of progress (the progress bar), since either one alone leaves out part of the picture.
The stepper is a pure display component driven by a single step value from its parent. The logic for whether the user can advance lives outside it, not inside it.
Small, non-technical details (like a security note, a confirmation line, or a theme toggle) do as much for how finished a flow feels as any of the four core components.

Conclusion

None of the four components in this flow are complicated individually. What makes a KYC flow work is the decisions around them: which choice comes first, where validation actually runs, and how honestly the interface talks to the user while something outside their control is being checked.

Whether the first draft comes from typing every line by hand or from scaffolding it with an MCP server and v0, that's the part worth spending time getting right before it ships.

Resources

Shadcn Components, the free component set used in this flow
ShadcnSpace, the base library these components extend
MCP server walkthrough
MDN: ARIA current attribute
Model Context Protocol specification

How the Chrome Dino Game Works Under the Hood: A Tour of Chromium's Source Code

Alex Oliinyk — Thu, 13 Aug 2026 17:44:25 +0000

You've seen it a hundred times: the Wi-Fi drops, Chrome shrugs, and a little pixelated T-Rex appears, ready to sprint through a desert the moment you hit the spacebar.

That tiny game, hidden behind the "No Internet" error since 2014, is played roughly 270 million times every month. Its internal codename at Google was "Project Bolan," a nod to Marc Bolan, frontman of the rock band T. Rex.

And because Chrome is built on the open-source Chromium project, the entire game – every constant, design decision, and hack – is sitting in public for anyone to read.

So I read it. All of it. And it turns out this "simple" game is a small masterclass in game design: it quietly onboards you, refuses to kill you unfairly, animates a moon through seven phases, and has been shipping a typo to billions of devices for a decade.

In this article, we'll walk through the real source code and unpack how the dino game actually works. If you want the game open in a tab while you read, you don't need to kill your Wi-Fi. You can play the Dinosaur Game online, and freeCodeCamp also has a guide to launching it on and offline.

And the code itself lives in the Chromium tree, browsable at source.chromium.org. This is historically a single file of roughly 3,000 lines of dependency-free vanilla JavaScript, drawing on a plain . No engine. No framework. Not even jQuery.

By the way, here's the entire game's artwork. It's one small PNG, with every sprite the code refers to by coordinates:

The Clock: Why the Game Runs the Same Speed Everywhere
The T-Rex: Four Constants and a Typo
The Fairness Engine: How the Game Refuses to Cheat You
Collision Detection: The Dino Is Six Rectangles
Night Mode and the Seven-Phase Moon
The Small Delights Hiding in Plain Sight
What You Can Steal for Your Own Projects

The Clock: Why the Game Runs the Same Speed Everywhere

The first problem every game has to solve: browsers don't repaint at a fixed rate. A 144 Hz gaming monitor fires requestAnimationFrame 144 times a second. But a struggling laptop might manage 40. If you move things a fixed number of pixels per frame, your game literally runs 3× faster on better hardware.

The dino's solution is the standard one, executed cleanly. The game defines its speeds in pixels per frame at an assumed 60 FPS, then scales every movement by how much time actually passed:

this.msPerFrame = 1000 / FPS;
// ...in each update:
this.xPos -= Math.floor((currentSpeed * FPS / 1000) * deltaTime);

Every moving thing in the game from the dino's jump to the cacti, clouds, and even the moon, is multiplied by deltaTime. That's why your high score is comparable to your friend's, whatever machines you're both on.

If you take one engineering habit away from this article, take this one: never move anything by "per frame" amounts. Always scale by elapsed time.

The T-Rex: Four Constants and a Typo

The dino's entire physical existence is defined by a handful of numbers in Trex.config and Runner.config:

GRAVITY: 0.6,
INIITAL_JUMP_VELOCITY: -10,
SPEED: 6,
ACCELERATION: 0.001,
MAX_SPEED: 13,

Yes, you read that right: INIITAL_JUMP_VELOCITY, with three I's. That misspelling shipped in Chrome, on billions of devices, and has survived for roughly a decade, because renaming it was never worth the risk. Let it comfort you the next time you find a typo in your own production code.

The units are pixels per frame at 60 FPS. Convert them and the physics becomes intuitive: gravity is 0.6 px/frame², jump velocity −10 px/frame. Run the math and the jump arc peaks at about 83 pixels roughly 0.28 seconds after takeoff. On a 150-pixel-tall playfield, that's more than half the screen.

The world starts scrolling at 6 px/frame (360 px/s) and gains 0.001 px/frame every frame until it hits the cap of 13, a little over twice the starting speed. That cap matters: it's the promise that the game gets hard, but never impossible.

But here's the detail most clones miss: the jump height is variable. Watch the code that runs when you release the spacebar:

endJump: function () {
    if (this.reachedMinHeight &&
        this.jumpVelocity < this.config.DROP_VELOCITY) {
        this.jumpVelocity = this.config.DROP_VELOCITY;
    }
},

Tap the spacebar and the dino does a short hop, but hold it and the dino rides the full arc. Releasing the key early clamps the upward velocity, cutting the jump short (as long as a minimum height was reached, so you can't glitch yourself into a cactus). And if you press the Down arrow mid-air, setSpeedDrop multiplies the fall speed by 3, slamming the dino back to the ground for a fast recovery.

Two tiny mechanics, and suddenly the single-button game has an expressive skill ceiling: short hop, full jump, fast slam. That's why the top players' runs look nothing like yours.

The Fairness Engine: How the Game Refuses to Cheat You

This is my favorite part of the codebase, because none of it is visible. You can only feel it. Every obstacle in the game is declared with a small config, and the configs encode a set of fairness rules. Here's the small cactus:

{
    type: 'CACTUS_SMALL',
    width: 17,
    height: 35,
    multipleSpeed: 4,
    minGap: 120,
    minSpeed: 0,
    // ...
}

Let's unpack the rules hiding in there and elsewhere in the spawning code:

Rule 1: The first three seconds are empty. CLEAR_TIME: 3000 guarantees no obstacle spawns for the first three seconds of a run. That's silent onboarding: you get a moment to feel the controls before the game asks anything of you.

Rule 2: Clusters are gated by speed. A cactus can spawn as a group of up to MAX_OBSTACLE_LENGTH: 3, but only when the current speed exceeds its multipleSpeed (4 for small cacti, 7 for large). Why? Because your jump distance grows with the world speed. The arc lasts a fixed time, so the faster the ground moves, the more ground you clear per jump.

Wide obstacles only appear once your jump is physically long enough to clear them. The game never generates a wall it knows you can't cross.

Rule 3: Gaps scale with speed too. The gap after each obstacle is computed as roughly obstacleWidth × speed + minGap × 0.6, plus randomness. So the faster the game, the more room you're given to react. Difficulty comes from the speed itself, never from unfair spacing.

Rule 4: No obstacle appears three times in a row. There's a function whose entire job is variety:

duplicateObstacleCheck: function (nextObstacleType) {
    var duplicateCount = 0;
    for (var i = 0; i < this.obstacleHistory.length; i++) {
        duplicateCount = this.obstacleHistory[i] == nextObstacleType ?
            duplicateCount + 1 : 0;
    }
    return duplicateCount >= Runner.config.MAX_OBSTACLE_DUPLICATION;
},

With MAX_OBSTACLE_DUPLICATION: 2, the spawner keeps a history and re-rolls if the same obstacle type would appear a third consecutive time. You've never noticed this rule, which is exactly the point. You'd have noticed its absence.

Rule 5: The pterodactyl is a late-game boss. Its config says minSpeed: 8.5, meaning it can't appear at all until you're two-thirds of the way to max speed. It flies at one of three heights (so sometimes you jump it, sometimes you duck, and sometimes at 50 pixels you must decide), it never spawns in groups (multipleSpeed: 999), and it has its own speedOffset: 0.8, meaning each pterodactyl flies slightly faster or slower than the world scrolls. That last detail breaks your rhythm-based muscle memory precisely when you've gotten comfortable.

Together these rules are the answer to a question every game designer faces: how do you make a game harder without making it unfair? Players can feel the difference between "I lost because I was slow" and "I lost because the game cheated". And the dino, in ten years and trillions of runs, has never cheated anyone.

Collision Detection: The Dino Is Six Rectangles

Naïve collision detection would wrap the dino in one bounding box and check overlap. But look at the dino: he has a snout sticking out, a tail, a gap under his chin. With a single box, a cactus grazing the empty air under his jaw would kill you, and it would feel terrible.

So the real dino is six boxes:

Trex.collisionBoxes = {
    RUNNING: [
        new CollisionBox(22, 0, 17, 16),   // head
        new CollisionBox(1, 18, 30, 9),    // torso
        new CollisionBox(10, 35, 14, 8),   // legs
        new CollisionBox(1, 24, 29, 5),
        new CollisionBox(5, 30, 21, 4),
        new CollisionBox(9, 34, 15, 4)
    ],
    DUCKING: [
        new CollisionBox(1, 18, 55, 25)    // one long low box
    ]
};

Six small rectangles that trace the dino's actual silhouette: head, torso, and a staircase of boxes down the belly and legs. When the dino ducks, the whole set is swapped for one long, low box.

The obstacles get the same treatment: a small cactus is three boxes tracing its trunk and arms, and the pterodactyl is five, following its wings and beak.

Here's what those boxes actually look like, drawn over the real sprites:

The algorithm is a classic two-phase check: first a cheap outer-box test (do the overall rectangles even touch?), and only if that passes, the detailed loop comparing every dino box against every obstacle box. Fast in the common case, precise in the moment that matters. If a cactus needle visually passes through the notch under the dino's chin, you live, and the code agrees with your eyes.

This is the cheapest possible version of a technique that scales all the way up to fighting-game hitboxes and hurtboxes. The lesson generalizes: collision should match what the player sees, not what's convenient for the math.

Night Mode and the Seven-Phase Moon

Reach 700 points (INVERT_DISTANCE: 700) and the world inverts: dark sky, pale ground, stars. Twelve seconds later (INVERT_FADE_DURATION: 12000), day returns. Numerically it's just a class toggle plus a CSS-style inversion of the palette. But the charming part is what happens in the sky.

The moon isn't a static sprite. The sprite sheet contains it in seven versions, and the code cycles through them:

NightMode.phases = [140, 120, 100, 60, 40, 20, 0];

Those are x-offsets into the sprite sheet, from a thin crescent through the half moons to a full disc:

Every time night falls, the moon advances one phase. Stars drift at their own speed (STAR_SPEED: 0.3), slower than the ground, giving the night a whisper of parallax depth. Nobody needed a lunar calendar in a browser error page. Somebody built one anyway, and that somebody understood that details like this are the difference between a feature and a beloved thing.

The Small Delights Hiding in Plain Sight

A few more finds from the source that reward the attentive:

The dino blinks. While the game waits for you to start, the idle dino blinks at randomized intervals. And there's a constant, MAX_BLINK_COUNT: 3, limiting how many times he'll do it. The blink delay itself is Math.ceil(Math.random() * Trex.BLINK_TIMING). Someone at Google tuned the randomness of a dinosaur's eyelid.

Your score isn't pixels. The distance meter multiplies actual pixels traveled by COEFFICIENT: 0.025. So a score of 100 means you've run 4,000 pixels. Every 100 points (ACHIEVEMENT_DISTANCE: 100), the score flashes at four beats per second – a tiny dopamine metronome that makes round numbers feel like events.

The counter is theatrical about overflow. The display shows MAX_DISTANCE_UNITS: 5 digits. Roll past 99,999 and the score visually resets. The internal counter keeps going, but the odometer effect stays, a deliberate homage to arcade cabinets.

Mobile players get a handicap. MOBILE_SPEED_COEFFICIENT: 1.2: the game runs faster... wait, no: it adjusts for the smaller screens and touch latency so the experience feels equivalent. The point is that someone measured the difference between a thumb on glass and a finger on a spacebar, and encoded the answer in a constant.

Restart is protected. After a crash there's a GAMEOVER_CLEAR_TIME: 750. For three-quarters of a second, your jump key won't restart the game. That's there because you will be hammering the spacebar when you die, and instantly restarting would rob you of the chance to see your score. A 750-millisecond act of mercy.

What You Can Steal for Your Own Projects

The dino game is a masterclass precisely because its constraints were brutal: it had to be tiny, load instantly, run on everything from gaming rigs to $50 phones, and be understood by anyone in one second.

The techniques it uses under those constraints transfer to any project:

Scale by time, not frames. Delta-time movement is why the game is fair across hardware.
Gate difficulty behind capability. Wide clusters appear only when the jump can clear them. Ask what the player can do, then spawn accordingly.
Give the player an empty runway. Three quiet seconds teach the controls better than a tutorial screen.
Enforce variety. A three-line history check prevents monotony the player would notice only as vague boredom.
Make hitboxes honest. Six rectangles that match the silhouette beat one rectangle that betrays the player's eyes.
Spend effort on invisible details. Blinking, moon phases, the restart grace period: none are necessary, but all are felt. Ten years on, the Chrome dino is proof that a great game doesn't need photorealistic graphics or a 100-gigabyte install. It just needs tight controls, fair rules, one button, and a moon that keeps its phases. Now you know exactly why it feels so good: because someone, line by line, made sure it would.

Go read the source. It's one of the best free game design lessons on the internet, and it's been hiding behind your worst Wi-Fi days all along.

How to Build a Browser-Based PDF Color Overlay Tool Using JavaScript

Bhavin Sheth — Thu, 13 Aug 2026 00:09:57 +0000

Sometimes you don't want to change the actual content of a PDF. You simply want to add a colored layer over part or all of the document.

This can be useful for creating branded reports, adding colored backgrounds, highlighting printed copies, producing design mockups, applying watermarked color effects, or preparing documents for presentations.

A PDF Color Overlay Tool makes this possible by placing a semi-transparent color layer over PDF pages while preserving the original text, images, and layout beneath it.

Instead of manually editing every page in graphic design software, users can upload a PDF, choose an overlay color, adjust its transparency, select a blend mode, decide where it should appear, preview the result, and download the updated document.

In this tutorial, you'll build this tool using JavaScript. Users will be able to upload a PDF and perform all the actions just mentioned – all without sending the document to a server.

What This PDF Color Overlay Tool Does and How It Works
Project Setup
Libraries Used
Creating the HTML Layout
Uploading and Previewing PDFs
Building the Overlay Settings
Applying Color Overlays to PDF Pages
Generating the Final PDF
Previewing the Result
Renaming and Downloading
Demo: How the PDF Color Overlay Tool Works
Performance Tips
Common Mistakes
Conclusion

What This PDF Color Overlay Tool Does and How It Works

A PDF Color Overlay Tool applies a colored layer on top of one or more pages while keeping the original PDF content visible underneath. Unlike a color inverter or grayscale converter, which permanently transform every pixel, a color overlay blends a selected color with the existing page using adjustable transparency and blend modes.

This makes it useful for creating branded documents, adding colored backgrounds, producing presentation-ready PDFs, highlighting sections, creating themed reports, or generating preview versions without modifying the original source document.

In this project, users can upload a PDF, preview every page, choose an overlay color using either a color picker or a hexadecimal value, adjust the overlay opacity, select a blend mode, choose where the overlay should appear, decide which pages should receive the effect, preview the updated document, and download the finished PDF directly from the browser.

Internally, PDF.js renders each page onto an HTML canvas. JavaScript then draws a colored rectangle over the rendered page using the selected transparency and blend mode. Once all selected pages have been processed, PDF-lib assembles the updated pages into a new downloadable PDF.

The overlay color is represented using a hexadecimal value.

const overlay = {
    color: "#667eea",
    opacity: 0.5
};

When drawing the overlay, JavaScript first sets the transparency level.

context.globalAlpha = overlay.opacity;

Next, the selected color is applied.

context.fillStyle = overlay.color;

Finally, the colored rectangle is drawn over the required area.

context.fillRect(0, 0, canvas.width, canvas.height);

Depending on the selected blend mode, the overlay can either gently tint the document, produce darker colors, create dramatic lighting effects, or generate completely different visual styles while preserving the original page underneath.

Project Setup

Before implementing the overlay functionality, let's create a simple project structure.

We'll build the application using HTML, CSS, and JavaScript, together with PDF.js, the Canvas API, and PDF-lib.

Our project structure looks like this:

pdf-color-overlay/
│── index.html
│── style.css
│── script.js
│── pdf.worker.min.js
│── assets/

Separating the HTML, CSS, and JavaScript keeps the project organized and makes future enhancements easier to implement.

Libraries Used

Our PDF Color Overlay Tool relies on three browser technologies that work together to render PDF pages, apply color overlays, and generate a new downloadable document.

PDF.js renders PDF pages directly inside the browser.

The HTML Canvas API draws the color overlay on top of each rendered page using transparency and blend modes.

PDF-lib generates the final PDF after all selected pages have been processed.

Include the required libraries before loading your application:

Configure the PDF.js worker.

pdfjsLib.GlobalWorkerOptions.workerSrc = "pdf.worker.min.js";

Using a worker allows PDF rendering to happen in the background, keeping the interface responsive even when opening large PDF files.

Creating the HTML Layout

The application is divided into four main sections:

Upload area
PDF preview
Overlay settings
Download section

Create the basic layout.

Initially, only the upload area is visible. The remaining sections appear after a PDF has been successfully loaded.

Selecting the Main Elements

Store references to the elements used throughout the application.

const uploadSection = document.getElementById("uploadSection");
const previewSection = document.getElementById("previewSection");
const settingsSection = document.getElementById("settingsSection");
const pdfCanvas = document.getElementById("pdfCanvas");

These references allow the application to update the interface without repeatedly searching the DOM.

Uploading and Previewing PDFs

The upload area supports both drag-and-drop and manual file selection.

Before loading the document, verify that the selected file is a PDF.

async function uploadPdf(file) {
    if (!file || file.type !== "application/pdf") {
        alert("Please select a PDF file.");
        return;
    }

    await loadPdf(file);
}

After validation, the PDF is loaded into memory for rendering.

Loading the PDF

Convert the uploaded file into an ArrayBuffer before opening it with PDF.js.

async function loadPdf(file) {
    const bytes = await file.arrayBuffer();
    pdfDocument = await pdfjsLib.getDocument({
        data: bytes
    }).promise;
    currentPage = 1;
    renderPage(currentPage);
}

Once the document has loaded successfully, the first page is rendered automatically.

Rendering PDF Pages

PDF.js renders one page at a time onto an HTML canvas.

Retrieve the selected page.

const page = await pdfDocument.getPage(currentPage);

Create the viewport.

const viewport = page.getViewport({
    scale: 1.5
});

Resize the canvas.

pdfCanvas.width = viewport.width;
pdfCanvas.height = viewport.height;

Render the page.

await page.render({
    canvasContext: pdfCanvas.getContext("2d"),
    viewport
}).promise;

After rendering completes, users can view the current page before applying any overlay effects.

Navigating Between Pages

Most PDF documents contain multiple pages, so the application includes simple navigation controls.

Store the current page.

let currentPage = 1;
let pdfDocument = null;

Move to the previous page.

previousButton.addEventListener("click", async () => {
    if (currentPage > 1) {
        currentPage--;
        await renderPage(currentPage);
    }
});

Move to the next page.

nextButton.addEventListener("click", async () => {
    if (currentPage < pdfDocument.numPages) {
        currentPage++;
        await renderPage(currentPage);
    }
});

Update the page indicator.

pageCounter.textContent = `Page ${currentPage} of ${pdfDocument.numPages}`;

Users can now browse through the uploaded PDF before deciding how the color overlay should be applied.

Building the Overlay Settings

After the PDF has been uploaded and previewed, users can configure how the color overlay should be applied. The settings panel lets users choose an overlay color, adjust its transparency, select a blend mode, specify where the overlay should appear, and decide which pages should receive the effect before generating the final PDF.

Choosing the Overlay Color

The first setting allows users to choose the color that will be placed over the PDF.

The application supports both a color picker and direct hexadecimal input.

Create the color picker.

Create the hexadecimal input.

Retrieve the selected color.

const overlayColor = document.getElementById("overlayColor").value;

If users enter a hexadecimal value manually, synchronize it with the color picker.

hexValue.addEventListener("input", () => {
    overlayColor.value = hexValue.value;
});

The selected color will later be drawn over the rendered PDF page.

Adjusting the Opacity

Opacity controls how transparent the overlay appears.

Lower values allow more of the original PDF to remain visible, while higher values create a stronger color effect.

Create the opacity slider.

Retrieve the selected value.

const opacity = Number(document.getElementById("opacity").value) / 100;

This value is later assigned to the canvas transparency before drawing the overlay.

Selecting the Blend Mode

Blend modes determine how the overlay color interacts with the original PDF content.

Create the dropdown.

Retrieve the selected blend mode.

const blendMode = document.getElementById("blendMode").value;

Each blend mode produces a different visual effect while preserving the document beneath the overlay.

Choosing the Overlay Position

The overlay doesn't always need to cover the entire page. Users can apply it only to specific regions if they want.

Create the available options.


Full Page

Header Only

Footer Only

Retrieve the selected position.

const position = document.querySelector('input[name="position"]:checked').value;

During processing, the application draws the overlay only inside the selected area.

Choosing Which Pages to Process

Users can apply the overlay in several different ways:

Current page only
Entire document
Separate overlay for every page
Specific pages

Create the page selection controls.


Current page only

All pages

Separate overlay per page

Specific pages

Retrieve the selected option.

const pageMode = document.querySelector('input[name="pages"]:checked').value;

Read the custom page range.

const pageRange = document.getElementById("pageRange").value.trim();

This flexibility allows users to apply different overlay strategies depending on the document.

Applying the Overlay

Once all settings have been configured, users can begin processing the PDF.

Create the action button.

Start the processing workflow.

applyOverlay.addEventListener("click", async () => {
    await processOverlay();
});

Starting Over

Users can reset the application at any time and upload another document.

Create the reset button.

Reset the tool.

resetTool.addEventListener("click", () => {
    location.reload();
});

The upload area becomes visible again, allowing another PDF to be processed without manually clearing every setting.

Applying Color Overlays to PDF Pages

Now we'll build the main feature of the application: adding a colored overlay to PDF pages.

The process begins by rendering each selected PDF page onto an HTML canvas using PDF.js. JavaScript then draws a semi-transparent colored rectangle over the page using the selected blend mode. Once all selected pages have been processed, PDF-lib generates a new downloadable PDF.

Applying the Overlay Color

Before drawing anything, retrieve the selected color.

const overlayColor = document.getElementById("overlayColor").value;

Set the canvas fill color.

context.fillStyle = overlayColor;

This color will be drawn over the selected portion of each PDF page.

Setting the Overlay Transparency

Opacity determines how much of the original page remains visible beneath the overlay.

Apply the selected transparency.

context.globalAlpha = opacity;

A lower opacity produces a subtle tint, while higher values create a stronger visual effect.

Applying the Blend Mode

Canvas supports several compositing modes that determine how the overlay interacts with the existing page.

Assign the selected blend mode.

context.globalCompositeOperation = blendMode;

Some common modes include:

Normal – Places the color directly over the page.
Multiply – Produces a darker appearance.
Overlay – Increases overall contrast.
Soft Light – Creates a gentle lighting effect.
Hard Light – Produces a stronger contrast.
Difference – Generates an inverted-style appearance based on color differences.

Drawing the Overlay

Once the color, opacity, and blend mode have been configured, draw the overlay on the canvas.

For a full-page overlay:

context.fillRect(0, 0, canvas.width, canvas.height);

If users choose Header Only, draw the rectangle across only the top section.

context.fillRect(0, 0, canvas.width, 120);

For Footer Only, draw the overlay near the bottom of the page.

context.fillRect(0, canvas.height - 120, canvas.width, 120);

These options allow different overlay styles without modifying the underlying PDF content.

Processing the Selected Pages

After configuring the overlay, process only the pages chosen by the user.

Loop through the selected pages.

for (let page = startPage; page <= endPage; page++) {
    await processPage(page);
}

Each processed page is temporarily stored before creating the final document.

If Current Page Only is selected, only the active page is processed. If All Pages is selected, the overlay is applied to the complete document.

Generating the Final PDF

Create a new PDF document.

const outputPdf = await PDFLib.PDFDocument.create();

Convert the processed canvas into an image.

const imageBytes = await canvasToBytes(pdfCanvas);

Embed the image.

const image = await outputPdf.embedPng(imageBytes);

Create a new page.

const page = outputPdf.addPage([
    image.width,
    image.height
]);

Draw the processed image.

page.drawImage(image, {
    x: 0,
    y: 0,
    width: image.width,
    height: image.height
});

Repeat these steps until every selected page has been added to the new PDF.

Saving the Generated PDF

Once all pages have been processed, save the completed document.

const pdfBytes = await outputPdf.save();

Create a downloadable file.

generatedPdfBlob = new Blob([pdfBytes], {
    type: "application/pdf"
});

The new PDF containing the selected color overlays is now ready for preview.

Previewing the Result

Before downloading the processed document, users should be able to review the final output. This makes it easy to verify that the selected color, opacity, blend mode, and page selection have been applied correctly.

Load the generated PDF.

let finalPdf = null;
async function showPreview() {
    const bytes = await generatedPdfBlob.arrayBuffer();
    finalPdf = await pdfjsLib.getDocument({
        data: bytes
    }).promise;
    renderFinalPage(1);
}

Render the selected page.

async function renderFinalPage(pageNumber) {
    const page = await finalPdf.getPage(pageNumber);

    const viewport = page.getViewport({
        scale: 1.5
    });

    previewCanvas.width = viewport.width;
    previewCanvas.height = viewport.height;

    await page.render({
        canvasContext: previewCanvas.getContext("2d"),
        viewport
    }).promise;
}

Users can navigate through the processed PDF before downloading it.

Renaming and Downloading

Before saving the generated PDF, users can customize the output filename.

Create the filename input.

Retrieve the filename.

function getFilename() {
    let filename = outputFilename.value.trim();

    if (!filename) {
        filename = "color-overlay.pdf";
    }

    if (!filename.toLowerCase().endsWith(".pdf")) {
        filename += ".pdf";
    }

    return filename;
}

Display information about the generated PDF.

pageCount.textContent = `${finalPdf.numPages} Pages`;
fileSize.textContent = formatFileSize(generatedPdfBlob.size);

Download the completed document.

downloadButton.addEventListener("click", () => {
    const url = URL.createObjectURL(generatedPdfBlob);
    const link = document.createElement("a");

    link.href = url;
    link.download = getFilename();
    link.click();

    URL.revokeObjectURL(url);
});

Everything happens locally inside the browser, helping users keep their PDF files private.

Demo: How the PDF Color Overlay Tool Works

Let's walk through the complete workflow.

Step 1: Upload the PDF

Users begin by dragging a PDF into the upload area or clicking Select PDF.

Step 2: Preview the Document

The uploaded PDF is rendered page by page, allowing users to review the document before applying any changes.

Step 3: Configure the Overlay

Users choose an overlay color, adjust the opacity, select a blend mode, choose the overlay position, and decide which pages should receive the effect.

Step 4: Apply the Overlay

Click Apply Overlay to process the selected pages using the chosen settings.

Step 5: Review the Processed PDF

The completed PDF appears in the preview window so users can verify the applied overlay before downloading.

Step 6: Rename and Download

Finally, users rename the output file if needed, review the page count and file size, and download the generated PDF.

Performance Tips

Large PDF files can take longer to process because every selected page must be rendered and updated. Processing only the required pages helps improve performance.

for (const page of selectedPages) {
    await processPage(page);
}

After downloading the file, release temporary resources to reduce memory usage.

URL.revokeObjectURL(downloadUrl);

These small optimizations help keep the application responsive when working with large multi-page PDF documents.

Common Mistakes

One common mistake is applying multiple overlays without first restoring the original page. Always render a fresh copy of the PDF page before applying another overlay.

await renderPage(currentPage);

Another issue is forgetting to restore the default canvas state after changing the opacity or blend mode.

context.globalAlpha = 1;
context.globalCompositeOperation = "source-over";

Finally, using a very high opacity can completely hide the original PDF content. Choosing an appropriate transparency level usually produces a more balanced result.

Conclusion

In this tutorial, you built a browser-based PDF Color Overlay Tool using JavaScript.

You learned how to upload PDF documents, render pages with PDF.js, configure overlay colors, adjust opacity, apply blend modes, position overlays, process selected pages, generate a new PDF with PDF-lib, preview the completed document, rename the output file, and download it directly from the browser.

Because the entire workflow runs locally, users can customize PDF documents without uploading sensitive files to an external server.

You can explore the complete workflow using the PDF Color Overlay Tool.

From here, you can extend the project with gradient overlays, custom overlay shapes, image overlays, reusable color presets, watermark templates, or additional PDF editing features for even greater flexibility.

How to Build a Browser-Based PDF Filter Studio with JavaScript

Bhavin Sheth — Wed, 12 Aug 2026 15:43:14 +0000

PDF editing isn't limited to adding signatures or merging documents. Sometimes you simply want to improve the appearance of a PDF by increasing brightness, boosting contrast, adding blur, converting it to grayscale, or applying creative visual effects – all without opening Photoshop or installing desktop software.

In this tutorial, you'll build a browser-based PDF Filter Studio using JavaScript, PDF.js, the Canvas API, and PDF-lib. Users can upload a PDF, preview each page, stack multiple filter layers, apply preset effects, process selected pages, preview the final document, rename it, and download the edited PDF directly from the browser.

Since every step runs locally, the uploaded PDF never leaves the user's device, making the application both fast and privacy-friendly.

What This PDF Filter Studio Does and How It Works
Why Build a PDF Filter Studio?
Project Setup
Libraries Used
Creating the HTML Layout
Uploading and Previewing PDFs
Building Filter Layers
Applying Filters to PDF Pages
Applying Preset Effects
Generating the Final PDF
Previewing the Result
Renaming and Downloading
Demo: How the PDF Filter Studio Works
Performance Tips
Common Mistakes
Conclusion

What This PDF Filter Studio Does and How It Works

Unlike tools that perform only a single operation, this PDF Filter Studio lets users combine multiple image adjustments before generating a new PDF.

After uploading a document, each page is rendered in the browser with PDF.js and displayed inside a preview window. Users can then create one or more filter layers, adjust values such as brightness, contrast, saturation, blur, opacity, grayscale, sepia, invert colors, or hue rotation, and instantly see how those settings affect the document.

For users who don't want to configure every adjustment manually, the application also includes preset effects like Grayscale, Sepia (Vintage), Invert (Negative), Sharpen, Glow, and Vignette. Once they've achieved the desired appearance, the selected filters are applied to the chosen pages, a new PDF is generated using PDF-lib, and the finished document can be reviewed, renamed, and downloaded without uploading files to any server.

This workflow provides a flexible way to enhance reports, presentations, scanned documents, marketing materials, and image-heavy PDFs directly inside the browser.

Why Build a PDF Filter Studio?

Most online PDF editors focus on structural changes such as merging, splitting, rotating, or compressing documents. Very few allow users to enhance the visual appearance of PDF pages using adjustable image filters.

A browser-based PDF Filter Studio fills that gap by combining document processing with image editing. Instead of exporting PDF pages into image-editing software, applying effects, and recreating the document, users can complete the entire workflow in one place.

Building this project is also an excellent way to learn several important web development concepts, including rendering PDF pages with PDF.js, processing images with the Canvas API, creating reusable filter pipelines, managing multiple filter layers, working with dynamic user interfaces, and generating new PDF files using PDF-lib.

Because every operation happens locally inside the browser, documents remain private while delivering fast performance and eliminating the need for additional software installations

Project Setup

Create a project folder with the following structure:

pdf-filter-studio/
│── index.html
│── style.css
│── script.js
│── assets/

The project is intentionally simple.

index.html builds the application interface.
style.css controls the layout and appearance.
script.js manages PDF rendering, filter processing, and PDF generation.
assets stores icons or other optional resources used by the application.

Once the folder structure is ready, we'll import the required libraries, build the upload interface, render PDF pages, and begin creating the filter system.

Libraries Used

This PDF Filter Studio combines three browser technologies to upload PDF files, render pages, apply multiple visual filters, and generate a brand-new downloadable PDF.

PDF.js is responsible for rendering PDF pages inside the browser.

The Canvas API applies brightness, contrast, blur, saturation, grayscale, sepia, invert, opacity, and hue rotation filters directly to each rendered page.

Finally, PDF-lib creates the edited PDF after all selected pages have been processed.

Include the required libraries before loading your JavaScript:

Configure the PDF.js worker.

pdfjsLib.GlobalWorkerOptions.workerSrc = "pdf.worker.min.js";

Using a worker keeps rendering smooth while JavaScript continues handling the user interface.

Creating the HTML Layout

The application is divided into four sections:

Upload Area
PDF Preview
Filter Panel
Download Section

Create the basic structure.

Initially only the upload section is visible. Once a PDF is selected, the remaining sections automatically appear.

Selecting DOM Elements

Store references to the elements used throughout the application.

const uploadSection = document.getElementById("uploadSection");
const previewCanvas = document.getElementById("previewCanvas");
const previousButton = document.getElementById("previousPage");
const nextButton = document.getElementById("nextPage");
const rotateLeftButton = document.getElementById("rotateLeft");
const rotateRightButton = document.getElementById("rotateRight");

Keeping references at the beginning of the script makes the rest of the code cleaner and easier to maintain.

Uploading and Previewing PDFs

The upload area supports both drag-and-drop and manual file selection.

Before loading the document, verify that the selected file is actually a PDF.

async function uploadPdf(file) {
    if (!file || file.type !== "application/pdf") {
        alert("Please choose a PDF file.");
        return;
    }

    await loadPdf(file);
}

Once validation succeeds, the document is loaded into memory.

Loading the PDF

Convert the uploaded file into an ArrayBuffer before opening it with PDF.js.

async function loadPdf(file) {
    const bytes = await file.arrayBuffer();
    pdfDocument = await pdfjsLib.getDocument({
        data: bytes
    }).promise;

    currentPage = 1;
    renderPage(currentPage);
}

After the document is loaded successfully, the first page is displayed automatically.

Rendering PDF Pages

Each page is rendered onto an HTML canvas.

Retrieve the selected page.

const page = await pdfDocument.getPage(currentPage);

Create a viewport.

const viewport = page.getViewport({
    scale: 1.5
});

Resize the canvas.

previewCanvas.width = viewport.width;
previewCanvas.height = viewport.height;

Render the page.

await page.render({
    canvasContext: previewCanvas.getContext("2d"),
    viewport
}).promise;

Every page now appears exactly as it exists inside the original PDF.

Navigating Between Pages

Most PDF files contain multiple pages, so users need simple navigation controls.

Store the current page.

let currentPage = 1;
let pdfDocument = null;

Move to the previous page.

previousButton.addEventListener("click", async () => {
    if (currentPage > 1) {
        currentPage--;
        await renderPage(currentPage);
    }
});

Move to the next page.

nextButton.addEventListener("click", async () => {
    if (currentPage < pdfDocument.numPages) {
        currentPage++;
        await renderPage(currentPage);
    }
});

Update the page counter.

pageIndicator.textContent = `Page ${currentPage} of ${pdfDocument.numPages}`;

Users can now browse through the document before adding filters.

Rotating the Preview

The application also includes preview rotation controls. Rotation affects only the preview, allowing users to inspect pages from different orientations before applying filters.

Store the current rotation angle.

let rotation = 0;

Rotate left.

rotateLeftButton.addEventListener("click", () => {
    rotation -= 90;
    renderPage(currentPage);
});

Rotate right.

rotateRightButton.addEventListener("click", () => {
    rotation += 90;
    renderPage(currentPage);
});

Apply the rotation when creating the viewport.

const viewport = page.getViewport({
    scale: 1.5,
    rotation
});

These controls improve the preview experience without modifying the original PDF.

The Filter Panel is the core of the PDF Filter Studio. Instead of applying a single effect, users can build a stack of filter layers, combine multiple adjustments, and preview the result before generating the final PDF.

Each filter layer represents one image adjustment such as Brightness, Contrast, Saturation, Blur, Opacity, Grayscale, Sepia, Invert Colors, or Hue Rotate.

Users can also apply one-click preset effects like Grayscale, Sepia (Vintage), Invert (Negative), Sharpen, Glow, and Vignette.

Creating Filter Layers

Instead of hardcoding every adjustment, we'll store filters inside an array.

const filters = [];

Each filter contains its type and value.

filters.push({
    type: "brightness",
    value: 120
});

Using this structure allows users to combine multiple filters in any order.

Adding a New Filter Layer

Users first select a filter from the dropdown, then click Add.

Create the dropdown.

Add the selected filter.

addButton.addEventListener("click", () => {
    filters.push({
        type: filterType.value,
        value: 100
    });

    renderFilters();
});

Each new filter immediately appears inside the Filter Layers panel.

Displaying Filter Layers

Whenever a filter is added, rebuild the filter list.

function renderFilters() {
    filterContainer.innerHTML = "";

    filters.forEach(createFilterCard);
}

Each filter card contains:

Filter name
Value slider
Current value
Delete button

This design makes it easy to manage multiple adjustments.

Updating Filter Values

Each layer contains its own slider.

Example for Brightness:

slider.addEventListener("input", event => {
    filter.value = Number(event.target.value);
    updatePreview();
});

The preview refreshes immediately whenever a slider changes.

The same logic is reused for every filter type.

Supporting Multiple Filter Types

Different filters use different ranges.

const ranges = {
    brightness: [0, 200],
    contrast: [0, 200],
    saturation: [0, 200],
    blur: [0, 20],
    opacity: [0, 100],
    grayscale: [0, 100],
    sepia: [0, 100],
    invert: [0, 100],
    hue: [0, 360]
};

This allows every adjustment to use the most appropriate values.

Preset Effects

Some users prefer one-click effects instead of manually creating filter layers.

The application includes several preset buttons.

Each preset simply creates one or more filter layers automatically.

For example, Grayscale:

function grayscalePreset() {
    filters.length = 0;

    filters.push({
        type: "grayscale",
        value: 100
    });

    updatePreview();
}

Users can still edit the generated layers afterwards.

Applying Filters to Specific Pages

Not every page needs the same effect. Users can choose where filters should be applied.

Create the page options.


Current page only

All pages

Specific pages

Retrieve the selected option.

const pageMode = document.querySelector('input[name="pages"]:checked').value;

If users choose Specific pages, read the page range.

const pageRange = document.getElementById("pageRange").value;

This allows users to edit only selected pages while leaving the rest unchanged.

Removing Filter Layers

Users can delete any filter before processing.

Create the delete function.

function removeFilter(index) {
    filters.splice(index, 1);
    renderFilters();
    updatePreview();
}

Removing a layer immediately updates the preview. This makes experimenting with different combinations quick and intuitive.

Applying Filters to PDF Pages

Now it's time to process the uploaded PDF.

Once users finish configuring their filter layers, the application renders every selected PDF page onto an HTML canvas, applies the configured filters in sequence, and generates a brand-new PDF using PDF-lib.

Unlike previous projects that applied only one effect, this Filter Studio supports multiple filter layers, allowing users to build their own image-processing pipeline.

Building the Canvas Filter String

The HTML Canvas API allows multiple filters to be combined into a single filter string.

Start with an empty string.

let filterString = "";

Loop through every filter layer.

filters.forEach(filter => {
    filterString += `${filter.type}
(${filter.value})
`;
});

Assign the completed filter string.

context.filter = filterString.trim();

Every active layer is now combined before rendering the page.

Drawing the Filtered Page

Once the filter string has been created, redraw the rendered PDF page.

context.drawImage(pdfCanvas, 0, 0);

The canvas now contains the filtered version of the page.

This approach allows several adjustments to be applied in a single rendering pass.

Applying Multiple Filter Layers

Since every adjustment is stored inside the filters array, users can combine effects however they like.

For example:

filters = [
    {
        type: "brightness",
        value: "130%"
    },
    {
        type: "contrast",
        value: "115%"
    },
    {
        type: "blur",
        value: "5px"
    }
];

These filters are automatically combined into one Canvas filter string before rendering.

This makes the application flexible while keeping the code simple.

Applying Preset Effects

Preset buttons simply replace the current filter list with predefined values.

Example for the Sepia preset:

filters = [
    {
        type: "sepia",
        value: "100%"
    }
];

updatePreview();

Likewise, the Glow preset may combine brightness and blur.

filters = [
    {
        type: "brightness",
        value: "125%"
    },
    {
        type: "blur",
        value: "2px"
    }
];

Preset effects save users time while still allowing manual adjustments afterward.

Processing Selected Pages

Once the filters are ready, process only the pages selected by the user.

for (const page of selectedPages) {
    await processPage(page);
}

If Current Page Only is selected, only the active page is processed.

If All Pages is selected, the loop processes every page in the document.

If users specify custom page numbers, only those pages are filtered.

Applying Filters

Users begin processing by clicking Apply Filters to PDF.

Create the action button.

Start processing.

applyFilters.addEventListener("click", async () => {
    await generatePdf();
});

While processing, display a loading indicator so users know the application is working.

Generating the Final PDF

Create a new PDF document.

const outputPdf = await PDFLib.PDFDocument.create();

Convert the filtered canvas into an image.

const imageBytes = await canvasToBytes(previewCanvas);

Embed the image.

const image = await outputPdf.embedPng(imageBytes);

Create a page.

const page = outputPdf.addPage([
    image.width,
    image.height
]);

Draw the processed image.

page.drawImage(image, {
    x: 0,
    y: 0,
    width: image.width,
    height: image.height
});

Repeat this process until every selected page has been added to the new PDF.

Saving the PDF

Once all pages have been processed, save the completed document.

const pdfBytes = await outputPdf.save();

Create the downloadable file.

generatedPdf = new Blob([pdfBytes], {
    type: "application/pdf"
});

The generated PDF is now ready for preview and download.

Previewing the Filtered Document

Before downloading, the application displays the processed PDF so users can verify the applied filters.

The preview includes page navigation and rotation controls, making it easy to inspect the final result before saving the file.

Starting Over

If users want to process another document, they can reset the application with a single click.

resetButton.addEventListener("click", () => {
    location.reload();
});

Reloading clears the uploaded PDF, removes all filter layers, resets preset effects, and returns the application to its initial upload screen.

Previewing the Result

Before downloading the edited document, it's helpful to let users review the processed PDF. This gives them an opportunity to verify that every selected filter has been applied correctly and make adjustments if necessary.

Load the generated PDF.

let finalPdf = null;

async function showPreview() {
    const bytes = await generatedPdf.arrayBuffer();

    finalPdf = await pdfjsLib.getDocument({
        data: bytes
    }).promise;

    renderPreviewPage(1);
}

Render the selected page.

async function renderPreviewPage(pageNumber) {
    const page = await finalPdf.getPage(pageNumber);
    const viewport = page.getViewport({
        scale: 1.5
    });

    previewCanvas.width = viewport.width;
    previewCanvas.height = viewport.height;

    await page.render({
        canvasContext: previewCanvas.getContext("2d"),
        viewport
    }).promise;
}

Users can browse every processed page before downloading the finished PDF.

Renaming and Downloading

Before saving the generated PDF, users can choose a custom filename.

Create the filename input.

Retrieve the filename.

function getFilename() {
    let filename = outputFilename.value.trim();

    if (!filename) {
        filename = "filtered-document.pdf";
    }

    if (!filename.toLowerCase().endsWith(".pdf")) {
        filename += ".pdf";
    }

    return filename;
}

Display useful information about the generated PDF.

pageCount.textContent = `${finalPdf.numPages} Pages`;
fileSize.textContent = formatFileSize(generatedPdf.size);

Download the document.

downloadButton.addEventListener("click", () => {
    const url = URL.createObjectURL(generatedPdf);
    const link = document.createElement("a");

    link.href = url;
    link.download = getFilename();
    link.click();

    URL.revokeObjectURL(url);
});

Everything happens locally inside the browser, helping protect users' documents and reducing upload time.

Demo: How the PDF Filter Studio Works

The complete workflow consists of just a few steps.

Step 1: Upload the PDF

Users begin by dragging a PDF into the upload area or clicking Select PDF.

Step 2: Preview the PDF

The uploaded document is rendered page by page using PDF.js. Users can navigate through the document and rotate pages before editing.

Step 3: Configure the Filters

Users create one or more filter layers, adjust brightness, contrast, saturation, blur, opacity, grayscale, sepia, invert colors, hue rotation, or apply preset effects.

Step 4: Apply the Filters

Click Apply Filters to PDF to process the selected pages.

Step 5: Review the Result

The completed PDF appears in the preview window for final verification.

Step 6: Rename and Download

Finally, users rename the output file if necessary, review the page count and file size, and download the edited PDF.

Performance Tips

Applying multiple filters to high-resolution PDF pages can increase processing time. Instead of processing the entire document every time, process only the selected pages.

for (const page of selectedPages) {
    await processPage(page);
}

Build the Canvas filter string only when filter values change instead of rebuilding it for every render.

context.filter = buildFilterString(filters);

After downloading the finished document, release temporary object URLs to free memory.

URL.revokeObjectURL(downloadUrl);

These optimizations help keep the application responsive, even when working with large multi-page PDF documents.

Common Mistakes

One common mistake is drawing a filtered page on top of an already filtered canvas. Always render the original PDF page before applying a new filter configuration.

await renderPage(currentPage);

Another issue is forgetting to reset the Canvas filter after processing.

context.filter = "none";

Finally, stacking too many heavy filters (such as Blur, Glow, and multiple contrast adjustments) can increase processing time and produce unexpected visual results. Applying only the filters you actually need generally produces cleaner output and better performance.

Conclusion

In this tutorial, you built a browser-based PDF Filter Studio using JavaScript.

You learned how to upload PDF documents, render pages with PDF.js, create reusable filter layers, apply brightness, contrast, saturation, blur, opacity, grayscale, sepia, invert colors, and hue rotation effects using the Canvas API, generate a new PDF with PDF-lib, preview the processed document, rename the output file, and download it directly from the browser.

Unlike single-purpose PDF editing tools, this project allows users to combine multiple visual effects into a flexible editing workflow while keeping all processing local to the browser.

You can explore the complete workflow using the PDF Filter Studio.

From here, you can extend the application with custom filter presets, AI-powered image enhancement, selective region filters, watermark overlays, or batch processing to create an even more powerful browser-based PDF editor.

How to Add Dynamic Features to a Static Site Without a Server

Manish Shivanandhan — Mon, 10 Aug 2026 14:13:37 +0000

Static sites are having a moment, and it makes sense. A folder of HTML, CSS, and JavaScript files is fast to load, cheap to host, and very hard to break.

Tools like Astro, Eleventy, and Hugo build that folder for you from Markdown files and templates. Hosts like Netlify, Vercel, and Cloudflare Pages then serve the result from a CDN, often for free.

Then your site needs to actually do something. A reader wants to leave a comment, or someone wants to email you. Maybe you want to show live prices, hide a page behind a login, or collect email addresses before a launch.

Most developers reach for a backend at this point. They spin up an Express app, add a database, and pick a hosting plan. Now they own a server, and servers need care forever.

The good news is that you often don't need one. Most dynamic features on a small site work fine without a server of your own, so here's how to think about the problem.

Static Does Not Mean Frozen
Start With What the Browser Already Does
Handling Form Submissions
Serverless Functions for the Rest
Databases and Logins You Can Rent
Comments, Search, and Payments
Know When You Have Outgrown It

Static Does Not Mean Frozen

The word "static" describes how your HTML reaches the browser, not what happens after it lands. A static site can still run all the JavaScript you want. It can fetch data, rewrite the page, listen for clicks, and talk to any public API.

There's only one thing it can't do, which is run your code before the page is sent. That means it can't keep a secret, query a private database, or make a decision based on who is asking.

That single limit is the whole design problem. Once you see it clearly, the rest is just sorting. Some work belongs in the browser, some belongs in a service you rent, and a small slice needs to run somewhere private.

Start With What the Browser Already Does

Check the platform before you add anything to your stack, because browsers ship with more power than most of us use.

The fetch API pulls JSON from any public endpoint. The

element gives you an accessible modal with no library, and

gives you an accordion. CSS now handles sticky headers, scroll-driven animation, and container queries, all of which used to need JavaScript.

A lot of features that seem to need a backend are really just a fetch call and a template string. A weather widget, a GitHub activity feed, a currency converter, a live score, or a Mastodon timeline: every one of those runs happily from the browser, because the data is public and the endpoint needs no key. Write the fetch, handle the loading and error states properly, and move on.

Handling Form Submissions

Forms are where most static sites hit their first real wall, because a submission has to go somewhere your visitors can't see. You can't put a database password in client-side code, and you can't send email straight from a browser.

Luckily this problem has been solved many times over, and most static hosts will handle forms for you. Netlify Forms needs one extra attribute on your form tag. After that, Netlify catches each submission at the edge, stores it in a dashboard, and either emails you or pings a webhook.

Sometimes you need more than that. Spam filters, file uploads, conditional logic, multi-step flows, payments inside the form, or rows that land in a spreadsheet with no glue code all point toward a dedicated tool. This roundup of the best form builders is a good way to compare your options, since the real differences come down to logic, integrations, and how much control you keep over the markup.

Either way, the choice is about ownership. Write your own form endpoint and you own the validation, the rate limits, the spam defense, the storage, the alerts, and the deletion requests that arrive under GDPR. That's a lot of work for a contact form. Build it yourself when the form is part of your product, and rent it when the form is just a way for people to reach you.

Serverless Functions for the Rest

Sooner or later you will need to run a few lines of code in private, whether to sign a request, hide an API key, or reshape a response before the browser sees it. That is exactly what serverless functions are for, and they're the smallest possible step away from a purely static site.

You drop a file into a folder, and your host turns it into a URL on the next deploy. That's the entire setup, and it works the same way in Netlify Functions, Vercel Functions, and Cloudflare Pages Functions. The code stays short:

export default async function handler(request) {
  const res = await fetch("https://api.example.com/data", {
    headers: { Authorization: `Bearer ${process.env.API_KEY}` },
  });
  const data = await res.json();
  return Response.json({ total: data.items.length });
}

Your key lives in an environment variable on the host, so the browser calls /api/handler and never sees it. There's no server to keep alive, no operating system to patch, and no bill on a quiet day.

This is the right home for anything that needs a credential. Use it to send email through Resend or Postmark, call an AI model, check a webhook signature, or proxy a paid API whose key would otherwise leak within a day.

Databases and Logins You Can Rent

State is the last piece people assume needs a server, but it does not. Supabase puts Postgres behind a REST API with row-level security. Those rules live in the database itself, so you can query it from the browser and still be safe. Firebase does much the same with a different data model, while Cloudflare D1 and Turso give you SQLite at the edge.

Logins follow the same pattern. Clerk, Auth0, and Supabase Auth all handle sessions, password resets, social logins, and two-factor codes behind a client SDK. Authentication is genuinely hard to get right, so leaning on an audited service here isn't laziness. It's sensible risk management.

Comments, Search, and Payments

The last few common features have drop-in answers too. Giscus turns GitHub Discussions into a comment box with a script tag and no database at all. Pagefind builds a search index while your site builds and ships it as static files, so full-text search costs you nothing at runtime.

Stripe covers money. Payment Links and Checkout let you sell something with a plain link, and Stripe handles the card, the tax, and the receipt. Your own site never touches card data.

Know When You Have Outgrown It

This model has a real ceiling, and you should be aware of it rather than fight it. Watch for a few signs: your logic is now spread across six services, your monthly SaaS bill beats the cost of a small server, cold starts are hurting real users, or you need long jobs, a queue, or a socket that stays open for hours. When that day comes, a regular application server is the simpler tool, so move.

Until then, this setup buys you things that matter. Your site stays fast by default, your attack surface stays small, and your time goes into the product instead of the plumbing. Start with the browser, add a function when you need a secret, and rent the hard parts.

Hope you enjoyed this article. You can connect with me on LinkedIn.

How to Build a Browser-Based PDF Color Inverter Tool Using JavaScript

Bhavin Sheth — Thu, 06 Aug 2026 22:17:36 +0000

Reading PDF documents for long periods can become tiring, especially when the document contains bright backgrounds or when you're working in a low-light environment.

In other situations, designers, developers, and print professionals may want to inspect how a document looks with inverted colors or prepare alternative versions for accessibility and review.

A PDF Color Inverter Tool makes this possible by transforming the colors of PDF pages while keeping the document structure intact. Instead of editing every image or graphic manually, users can upload a PDF, invert its colors, preview the results, and download a newly generated document in just a few clicks.

In this tutorial, you'll build a browser-based PDF Color Inverter Tool using JavaScript. Users will be able to upload a PDF, preview its pages, choose an inversion mode, specify the page range to process, adjust the output quality, enable live preview, generate the inverted PDF, review the result, rename the output file, and download it, all without uploading the document to a server.

We'll use PDF.js to render PDF pages inside the browser, the HTML Canvas API to manipulate pixel colors, and PDF-lib to generate the final PDF.

By the end of this tutorial, you'll have a fully functional client-side PDF color inversion tool similar to the one available on my site All In One Tools.

What This PDF Color Inverter Tool Does and How It Works
Project Setup
Creating the HTML Layout
Uploading and Previewing PDFs
Building the Color Inversion Settings
Inverting PDF Colors
Generating the Final PDF
Previewing the Result
Renaming and Downloading
Demo: How the PDF Color Inverter Tool Works
Performance Tips
Common Mistakes
Conclusion

What This PDF Color Inverter Tool Does and How It Works

A PDF Color Inverter Tool changes the appearance of a PDF by reversing the colors of its pages. Light colors become dark, dark colors become light, and every pixel is recalculated to create an inverted version of the original document. This can improve readability in certain environments, help preview designs in dark mode, or simply provide an alternative way to view a document.

In this project, users can upload a PDF, browse through every page, choose how the colors should be inverted, define the page range to process, select the output quality, enable a live preview, generate the inverted document, rename the output file, and download the finished PDF. Since all processing happens locally inside the browser, the original document never leaves the user's device.

Behind the scenes, PDF.js renders each PDF page onto an HTML canvas. Once a page is rendered, JavaScript accesses the pixel data using the Canvas API. Every pixel's red, green, and blue values are recalculated to create the inverted version of the page.

After processing all selected pages, PDF-lib assembles the modified pages into a new PDF that users can preview and download.

A single pixel is represented by four values:

const pixel = {

    red: 120,

    green: 85,

    blue: 200,

    alpha: 255

};

During color inversion, each color channel is transformed by subtracting its value from 255.

red = 255 - red;

green = 255 - green;

blue = 255 - blue;

Repeating this calculation for every pixel on every selected page produces the final inverted PDF while preserving the document's layout, page order, and dimensions.

Project Setup

Before writing any image-processing code, let's create a simple project structure for our PDF Color Inverter Tool.

We'll build the application using plain HTML, CSS, and JavaScript together with two libraries:

PDF.js for rendering PDF pages inside the browser.
PDF-lib for generating the final inverted PDF.

Our project structure looks like this:

pdf-color-inverter/

│── index.html
│── style.css
│── script.js
│── pdf.worker.min.js
│── assets/

Keeping everything separated makes the application easier to understand and maintain.

Include the required libraries before loading your own JavaScript.

Configure the PDF.js worker.

pdfjsLib.GlobalWorkerOptions.workerSrc =
    "pdf.worker.min.js";

Running PDF.js inside a worker keeps the browser responsive while rendering large PDF files.

Creating the HTML Layout

The application contains four primary sections:

Upload area
Settings panel
PDF preview
Result section

Create the basic structure.

Only the upload area is visible when the page first loads.

After a PDF has been selected, the remaining sections become available.

Selecting the Main Elements

Store references to the elements used throughout the application.

const uploadSection =
document.getElementById(
    "uploadSection"
);

const settingsSection =
document.getElementById(
    "settingsSection"
);

const previewSection =
document.getElementById(
    "previewSection"
);

const resultSection =
document.getElementById(
    "resultSection"
);

const pdfCanvas =
document.getElementById(
    "pdfCanvas"
);

These references make it easy to switch between different stages of the workflow.

Uploading and Previewing PDFs

The upload area accepts drag-and-drop as well as manual file selection.

When a file is selected, verify that it's actually a PDF.

async function handleUpload(
    file
) {

    if (
        !file ||
        file.type !==
        "application/pdf"
    ) {

        alert(
            "Please select a PDF file."
        );

        return;

    }

    await loadPdf(file);

}

If the file passes validation, the browser loads it into memory.

Supporting Password-Protected PDFs

Some documents are protected with a password.

The upload screen provides an optional password field before processing begins.

Retrieve the entered password.

const password =
document
.getElementById(
    "pdfPassword"
)
.value
.trim();

Pass the password to PDF.js while loading the document.

const loadingTask =
pdfjsLib.getDocument({

    data: pdfBytes,

    password

});

pdfDocument =
await loadingTask.promise;

If the document isn't password protected, the password field can simply remain empty.

Loading the PDF

Convert the uploaded file into an ArrayBuffer.

async function loadPdf(
    file
) {

    originalPdfBytes =
    await file.arrayBuffer();

    pdfDocument =
    await pdfjsLib
        .getDocument({

            data:
            originalPdfBytes

        })
        .promise;

    currentPage = 1;

    await renderPage(
        currentPage
    );

}

The original bytes are preserved because they'll later be used to generate the inverted PDF.

Rendering PDF Pages

PDF.js renders one page at a time.

Retrieve the requested page.

async function renderPage(
    pageNumber
) {

    const page =
    await pdfDocument.getPage(
        pageNumber
    );

    const viewport =
    page.getViewport({

        scale: 1.5

    });

Resize the canvas.

pdfCanvas.width =
viewport.width;

pdfCanvas.height =
viewport.height;

Render the page.

await page.render({

    canvasContext:

    pdfCanvas.getContext(
        "2d"
    ),

    viewport

}).promise;

After rendering completes, the selected page becomes visible inside the preview area.

Navigating Between Pages

Most documents contain multiple pages, so the preview includes Previous and Next buttons.

Create the page state.

let currentPage = 1;

let pdfDocument = null;

Move to the previous page.

previousButton
.addEventListener(

"click",

async () => {

    if (
        currentPage > 1
    ) {

        currentPage--;

        await renderPage(
            currentPage
        );

    }

});

Move to the next page.

nextButton
.addEventListener(

"click",

async () => {

    if (

        currentPage <

        pdfDocument.numPages

    ) {

        currentPage++;

        await renderPage(
            currentPage
        );

    }

});

Update the page indicator.

pageNumber.textContent =

`Page ${currentPage} of ${pdfDocument.numPages}`;

This allows users to browse through the document before choosing which pages should have their colors inverted.

Building the Color Inversion Settings

Before processing the PDF, users should be able to control how the colors are inverted. The settings panel lets users choose the inversion mode, specify which pages should be processed, select the output quality, enable a live preview, or reset everything and start over.

Choosing the Inversion Mode

The first option allows users to choose how the document colors should be inverted.

Create the dropdown.

Read the selected mode.

const inversionMode =

document
.getElementById(
    "invertMode"
)
.value;

The selected value determines which color transformation is applied during processing.

Selecting the Page Range

Sometimes users only need to invert a few pages instead of the entire document.

Create two input fields.

Retrieve the selected pages.

const startPage =

Number(
startPageInput.value
);

const endPage =

Number(
endPageInput.value
);

Only the pages inside this range will be processed when generating the final PDF.

Choosing the Output Quality

The tool provides multiple quality levels so users can balance image quality and file size.

Create the quality selector.

Read the selected quality.

const quality =

document
.getElementById(
    "outputQuality"
)
.value;

The selected value will later determine the image quality used while generating the new PDF.

Enabling Live Preview

The Live Preview switch lets users instantly see the inverted colors without generating a new PDF.

Create the toggle.

Read its state.

const livePreview =

document
.getElementById(
    "livePreview"
)
.checked;

Whenever the setting changes, refresh the preview.

livePreviewToggle
.addEventListener(

"change",

updatePreview

);

When enabled, the preview canvas updates automatically as users change the inversion settings.

Resetting the Settings

The Reset button clears the current configuration so users can begin again without reloading the page.

Create the button.

Restore the default values.

function resetSettings() {

    invertMode.value =
    "full";

    outputQuality.value =
    "high";

    livePreview.checked =
    false;

}

Attach the event listener.

resetButton
.addEventListener(

"click",

resetSettings

);

This returns the settings panel to its initial state.

Starting the Color Inversion

Once the settings have been reviewed, users can begin processing the document.

Create the action button.

Start the inversion process.

invertButton
.addEventListener(

"click",

async () => {

    await invertPdf();

});

Inverting PDF Colors

Now we'll build the core feature of the application: reversing the colors of each PDF page.

The workflow is straightforward. First, PDF.js renders a page onto an HTML canvas. Next, JavaScript reads every pixel from the canvas, inverts its red, green, and blue values, and writes the updated pixels back. Finally, the processed page is added to a new PDF using PDF-lib.

Reading Canvas Pixel Data

Once a page has been rendered, retrieve its pixel information.

const imageData =

context.getImageData(

    0,

    0,

    canvas.width,

    canvas.height

);

Each pixel consists of four values:

Red
Green
Blue
Alpha (Transparency)

The pixel data is stored inside an array.

const pixels =
imageData.data;

We'll modify this array directly.

Inverting Every Pixel

To invert a color, subtract each RGB value from 255.

Loop through every pixel.

for (

    let i = 0;

    i < pixels.length;

    i += 4

) {

    pixels[i] =
    255 - pixels[i];

    pixels[i + 1] =
    255 - pixels[i + 1];

    pixels[i + 2] =
    255 - pixels[i + 2];

}

The alpha channel remains unchanged so transparent elements continue to render correctly.

After updating every pixel, write the modified image back onto the canvas.

context.putImageData(

    imageData,

    0,

    0

);

The page preview now displays the inverted colors.

Updating the Live Preview

If Live Preview is enabled, users should immediately see the changes without generating a new PDF.

Check whether the feature is active.

if (

    livePreview.checked

) {

    await invertCurrentPage();

}

Whenever users change the inversion mode, page range, or quality settings, refresh the preview.

async function updatePreview() {

    await renderPage(

        currentPage

    );

    await invertCurrentPage();

}

Processing the Selected Pages

Instead of processing the entire document every time, only invert the pages selected by the user.

Loop through the chosen page range.

for (

    let page = startPage;

    page <= endPage;

    page++

) {

    await processPage(
        page
    );

}

Each processed page is temporarily stored before generating the final PDF.

Generating the Final PDF

Create a new PDF document.

const outputPdf =

await PDFLib
.PDFDocument
.create();

Convert the processed canvas into an image.

const imageBytes =

await canvasToBytes(
    pdfCanvas
);

Embed the image.

const image =

await outputPdf
.embedPng(
    imageBytes
);

Create a page.

const page =

outputPdf.addPage([

    image.width,

    image.height

]);

Draw the processed image.

page.drawImage(

    image,

    {

        x: 0,

        y: 0,

        width: image.width,

        height: image.height

    }

);

Repeat these steps for every selected page.

Saving the Finished PDF

Once all pages have been processed, save the completed document.

const pdfBytes =

await outputPdf.save();

Convert the generated bytes into a downloadable file.

generatedPdfBlob =

new Blob(

    [pdfBytes],

    {

        type:
        "application/pdf"

    }

);

The generated PDF is now ready for preview and download.

Previewing the Result

Before downloading the processed document, it's useful to let users review the final output. This allows them to verify that the selected pages have been inverted correctly and that the document appears as expected.

Load the generated PDF into PDF.js.

async function showPreview() {

    const bytes =
        await generatedPdfBlob
            .arrayBuffer();

    finalPdf =
        await pdfjsLib
            .getDocument({

                data: bytes

            })
            .promise;

    renderFinalPage(1);

}

Render the selected page.

async function renderFinalPage(
    pageNumber
) {

    const page =
        await finalPdf.getPage(
            pageNumber
        );

    const viewport =
        page.getViewport({

            scale: 1.5

        });

    finalCanvas.width =
        viewport.width;

    finalCanvas.height =
        viewport.height;

    await page.render({

        canvasContext:
        finalCanvas
            .getContext("2d"),

        viewport

    }).promise;

}

Users can browse through the processed document before downloading it.

Renaming and Downloading

Before saving the PDF, users can provide a custom filename.

Create the filename field.

Retrieve the filename.

function getFilename() {

    let filename =

    outputFilename
        .value
        .trim();

    if (!filename) {

        filename =
        "inverted-document.pdf";

    }

    if (
        !filename
        .endsWith(".pdf")
    ) {

        filename += ".pdf";

    }

    return filename;

}

Display additional file information.

pageCount.textContent =

`${finalPdf.numPages} Pages`;

fileSize.textContent =

formatFileSize(

    generatedPdfBlob.size

);

Download the generated PDF.

downloadButton
.addEventListener(

"click",

() => {

    const url =

    URL.createObjectURL(
        generatedPdfBlob
    );

    const link =
        document.createElement(
            "a"
        );

    link.href =
        url;

    link.download =
        getFilename();

    link.click();

    URL.revokeObjectURL(
        url
    );

});

Everything happens locally inside the browser, so users can download the processed PDF immediately after reviewing it.

Demo: How the PDF Color Inverter Tool Works

Let's walk through the complete workflow.

Step 1: Upload the PDF

Users begin by dragging a PDF into the upload area or clicking Select PDF. If the document is password protected, the password can be entered before loading.

Step 2: Preview the Document

The uploaded PDF is rendered page by page, allowing users to browse the document before making any changes.

Step 3: Configure the Settings

Users choose the page range, output quality, and whether Live Preview should be enabled.

Step 4: Preview the Inverted Colors

When Live Preview is enabled, the current page updates immediately so users can review the inverted appearance before processing the complete document.

Step 5: Generate the PDF

Clicking Invert PDF Colors processes the selected pages and creates a new PDF containing the inverted pages.

Step 6: Review and Download

The generated PDF appears in the final preview. Users can rename the output file, review the page count and file size, and download the completed document.

Performance Tips

Large PDF files can require additional processing time. Rendering only the current page, updating the preview instead of reloading the entire document, and processing only the selected page range can significantly improve performance.

for (

    let page = startPage;

    page <= endPage;

    page++

) {

    await processPage(
        page
    );

}

After the download completes, release temporary resources.

URL.revokeObjectURL(
    downloadUrl
);

These small optimizations help keep the application responsive, even when processing large PDF files.

Common Mistakes

A common mistake is modifying the original canvas repeatedly without first rendering a fresh copy of the PDF page. This can cause colors to be inverted multiple times.

Always render the original page before applying another inversion.

await renderPage(
    currentPage
);

Another issue is processing page numbers outside the valid range.

if (

    pageNumber < 1 ||

    pageNumber >

    pdfDocument.numPages

) {

    return;

}

Finally, remember that higher output quality generally produces larger PDF files. Users should choose a quality level that balances image clarity and file size for their specific needs.

Conclusion

In this tutorial, you built a browser-based PDF Color Inverter Tool using JavaScript.

You learned how to upload PDF documents, support password-protected files, render pages with PDF.js, manipulate pixel colors using the HTML Canvas API, generate a new PDF with PDF-lib, preview the completed document, rename the output file, and download it directly from the browser.

Because all processing takes place locally, users can invert PDF colors without uploading sensitive documents to an external server.

You can explore the complete workflow using the PDF Color Inverter Tool.

This project can be extended further by adding custom color filters, selective page previews, brightness and contrast adjustments, grayscale conversion, sepia effects, batch processing, or additional document enhancement tools.

How to Build an Open Source SaaS Landing Page Template with shadcn/ui

Ash — Mon, 03 Aug 2026 18:39:33 +0000

Most SaaS landing pages share the same core sections: a hero, social proof, features, pricing, FAQ, and a footer. And most developers end up building these from scratch on every project. That's repetition, not engineering.

So I built and open-sourced a complete SaaS landing page template called ChatDeck. It runs on Next.js 16, React 19, shadcn/ui with the new base-nova style, Tailwind CSS v4, and TypeScript. The full source is on GitHub under the MIT license. I built and open-sourced this template, and everything here comes from decisions made during that process.

Building it forced me to make real decisions on a stack that moved significantly in the past 12 months. This article is about those decisions: what worked, what didn't, and what I'd do differently if I started today.

Prerequisites: This article assumes you're comfortable with React and TypeScript. Some familiarity with the Next.js App Router is helpful but not required. Each lesson is explained from first principles.

The Stack Choices and Why They Matter
Getting Started
Project Structure
Lesson 1: shadcn/ui's Newbase-novaStyle Changes What "Accessible" Means
Lesson 2: Tailwind CSS v4 Requires a Mental Model Shift
Lesson 3: OKLCH Colors Make Dark Mode Predictable
Lesson 4: Page Architecture — Flat Beats Clever
Lesson 5: Staggered Animations Without Managing Individual Delays
Lesson 6: CSS-Only Infinite Scroll — No Library Needed
Lesson 7: CSS Subgrid Solves Pricing Card Alignment Natively
Lesson 8: Inline SVGs Beat Image Libraries for Simple Logos
What I'd Do Differently
Summary

The Stack Choices and Why They Matter

Before getting into the code, here's what the template runs on. Each choice was deliberate — none of these are defaults you get from create-next-app.

Technology	Version	Why I chose it
Next.js	^16.0.3	App Router gives you React Server Components out of the box. Static sections like Hero and Features render on the server — no client-side JS needed for content that never changes.
React	19.2.0	React 19 stabilises the `use` hook and concurrent features. Staying on the latest version means the template doesn't immediately feel stale.
shadcn/ui	^4.13.0 (CLI)	Components are copied into your codebase, not installed as a package. You own the code. No version lock-in, no fighting library defaults when you need to customize.
Base UI (`@base-ui/react`)	^1.6.0	shadcn/ui's new `base-nova` style uses Base UI instead of Radix as its headless primitive layer. It has a smaller peer dependency footprint and tighter ARIA integration. More on this in Lesson 1.
Tailwind CSS	^4	v4 moves theme configuration from a JavaScript config file into CSS directly. Custom animations, color tokens, and radius scales all live in `globals.css`. More on this in Lesson 2.
Motion (`motion/react`)	^12.23.24	The rebranded Framer Motion. Handles entrance animations on the Hero and scroll-triggered animations on the Features section. Chosen over CSS animations because staggered sequences are much simpler to manage.
TypeScript	^5	Full type safety throughout. Component props, icon maps, pricing plan objects — all typed. Catches errors at build time, not at runtime.
Lucide React	^0.553.0	Consistent, well-maintained icon set that works cleanly with Tailwind's `size-*` utilities. No custom SVG wrangling needed for UI icons.

The most interesting decisions in this list are the ones that reflect how the ecosystem changed in the past year: Base UI replacing Radix inside shadcn/ui, and Tailwind v4's shift to CSS-first configuration. The lessons below walk through each of these in detail, starting with the choices that had the biggest impact on how the code is actually written.

Getting Started

Before diving into the lessons, here's how to get the project running locally. Having it open alongside this article makes the code examples easier to follow.

git clone https://github.com/ShadcnDeck/chatdeck-shadcn-saas-landing-page-template.git
cd chatdeck-shadcn-saas-landing-page-template
pnpm install
pnpm dev

Open http://localhost:3000 and you'll see the full landing page running locally.

All section content lives as plain TypeScript arrays inside each Block component. To change the features, edit the features array in FeatureSection.tsx. To change pricing tiers, edit the plans array in PricingSection.tsx. No CMS, no config files — just TypeScript objects.

To customize colors, update the OKLCH values in app/globals.css under the :root block. Change --primary and every button, link, and accent color updates across the entire template.

Deploy to Vercel with a single vercel command or by pushing to GitHub and connecting the repo. Next.js is detected automatically.

Project Structure

Here's the full directory layout before we go through each part of it:

chatdeck/
├── app/
│   ├── globals.css         # Theme tokens + custom animations (Tailwind v4 @theme)
│   ├── layout.tsx          # Root layout — Navbar, Footer, fonts
│   └── page.tsx            # Section imports — 16 lines
├── components/
│   ├── Blocks/             # Page sections (Hero, Features, Pricing, etc.)
│   ├── ui/                 # shadcn/ui components — base-nova style
│   └── navbar.tsx          # Scroll-aware sticky navbar
└── lib/
    └── utils.ts            # cn() helper (clsx + tailwind-merge)

The key separation is Blocks/ vs ui/. The ui/ folder holds primitive components — Button, Badge, Accordion — that come from shadcn/ui and rarely change. The Blocks/ folder holds page-level sections that are specific to this template and change often. When you're customising, you mostly work in Blocks/. When you upgrade shadcn/ui components, you touch ui/.

The lessons below go through specific files in this structure piece by piece: components.json and ui/accordion.tsx in Lesson 1, app/globals.css in Lessons 2 and 3, app/page.tsx in Lesson 4, and the individual Block components in Lessons 5 through 8.

Lesson 1: shadcn/ui's New `base-nova` Style Changes What "Accessible" Means

If you've used shadcn/ui before, you know the default setup uses Radix UI primitives, headless components that handle focus management, keyboard navigation, and ARIA attributes. Radix has been the default for years.

But shadcn/ui introduced a new style in 2025 called base-nova, which replaces Radix with Base UI, the headless primitive library from MUI.

Based on shadcn's public direction and the components released through 2025, base-nova appears to be the intended default going forward (though shadcn hasn't yet deprecated the Radix style).

In the project's components.json:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "iconLibrary": "lucide"
}

The "style": "base-nova" line means every component the shadcn/ui CLI installs wraps Base UI primitives instead of Radix. To understand what this changes in practice, here's what the same Accordion trigger component looks like in the older Radix-based default style:

// Radix-based default style (the old way)
import * as AccordionPrimitive from "@radix-ui/react-accordion"

const AccordionTrigger = React.forwardRef<
  React.ElementRef,
  React.ComponentPropsWithoutRef
>(({ className, children, ...props }, ref) => {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    
       setIsOpen(!isOpen)}
        {...props}
      >
        {children}
        
        
      
    
  )
})

Notice the useState(false) tracking whether the accordion is open, and the onClick handler that toggles it. This means the component has to manually keep its own isOpen state in sync with what Radix internally knows about the open/closed state.

Now here's the same component using the base-nova style with Base UI:

// components/ui/accordion.tsx — base-nova style (the new way)
import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion"

function AccordionTrigger({ className, children, ...props }: AccordionPrimitive.Trigger.Props) {
  return (
    
      
        {children}
        
        
      
    
  )
}

No useState. No onClick. No isOpen variable. The chevron visibility is controlled entirely by group-aria-expanded/accordion-trigger:hidden — a Tailwind class that reads the aria-expanded attribute Base UI sets automatically on the trigger element.

The lesson here: in the Radix version, you have two parallel systems: the component's own isOpen state, and the ARIA attributes that the library manages separately for screen readers. These can drift out of sync — for example, if the accordion closes via keyboard navigation, the ARIA state updates correctly but your isOpen state doesn't unless you wire up the right callbacks. In the Base UI version, there is only one system. ARIA state IS the state. Tailwind reads it directly. There's nothing to keep in sync and nothing that can drift.

Lesson: use the primitive library's ARIA attributes as your source of truth for visual state. If your headless component library already sets aria-expanded, aria-selected, or aria-checked, Tailwind can respond to those directly with aria-* variant classes — no parallel JavaScript state needed.

So when you install shadcn/ui today, choose base-nova over the default Radix style. You get tighter Base UI integration, a smaller peer dependency footprint, and components that are more aligned with where the ecosystem is moving.

Lesson 2: Tailwind CSS v4 Requires a Mental Model Shift

Tailwind CSS v4 moves primary theme configuration out of the JavaScript config file and into CSS. This sounds small. In practice, it changes how you think about the entire theming system.

In Tailwind v3, you'd extend the theme in tailwind.config.js:

// OLD — tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      animation: {
        marquee: "marquee 40s linear infinite",
      },
      keyframes: {
        marquee: {
          from: { transform: "translateX(0)" },
          to: { transform: "translateX(calc(-100% - var(--gap)))" },
        },
      },
    },
  },
}

In Tailwind v4, that same configuration lives in your CSS file instead:

/* app/globals.css — Tailwind v4 */
@import "tailwindcss";

@theme inline {
  --animate-marquee: marquee var(--duration) infinite linear;
  --animate-marquee-vertical: marquee-vertical var(--duration) linear infinite;

  @keyframes marquee {
    from { transform: translateX(0); }
    to   { transform: translateX(calc(-100% - var(--gap))); }
  }

  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --radius-4xl: calc(var(--radius) * 2.6);
}

The @theme inline block extends Tailwind's design token system. Define --animate-marquee here and you can use className="animate-marquee" anywhere in your components. Tailwind generates the utility class automatically from the CSS variable.

Custom animations, radius scales, and color tokens all live in CSS now. The benefit is that CSS is where styles belong. The config file was always an indirection layer between "what I want my design system to look like" and "where that actually lives." Tailwind v4 removes the indirection.

The friction: if you start a Tailwind v4 project with a v3 mental model, you'll spend time looking for theme config in the wrong place. Read the v4 migration guide before you start, not after you're confused.

Lesson: move your mental model of "theme config" from JavaScript to CSS. In Tailwind v4, if you want a custom animation, a new radius scale, or a color token, define it in @theme inline inside globals.css. That's where it belongs, and that's where every developer on your team will find it.

Lesson 3: OKLCH Colors Make Dark Mode Predictable

The template uses OKLCH color values throughout, not hex or HSL:

:root {
  --background: oklch(1 0 0);        /* white */
  --foreground: oklch(0.145 0 0);    /* near-black */
  --primary: oklch(0.205 0 0);
  --border: oklch(0.922 0 0);
}

.dark {
  --background: oklch(0.145 0 0);    /* near-black */
  --foreground: oklch(0.985 0 0);    /* near-white */
  --primary: oklch(0.922 0 0);
  --border: oklch(1 0 0 / 10%);      /* white at 10% opacity */
}

OKLCH is a perceptually uniform color space. When you increase the lightness value in OKLCH, the color actually looks lighter to human eyes, consistently. Hex and HSL don't guarantee this. You can increase the L in HSL and get a color that looks the same or even darker depending on the hue.

For dark mode specifically, this matters because you're inverting a whole color system. With HSL, you'll often end up manually tweaking individual color values until contrast ratios look right. With OKLCH, increasing or decreasing the lightness value gives you predictable results across all your tokens.

The dark mode switch itself is zero JavaScript. Adding class="dark" to the element swaps every CSS variable. Tailwind reads the updated variables and re-renders every component. There's no context provider and no useTheme hook needed for the CSS layer — just a class toggle on the root element.

Lesson: swap your color tokens to OKLCH. When defining dark mode values, adjust the first OKLCH parameter (lightness) and the result will look predictably lighter or darker. With hex or HSL you're often guessing; with OKLCH you're reasoning.

Lesson 4: Page Architecture — Flat Beats Clever

The main page file is 16 lines:

// app/page.tsx
import Hero from "@/components/Blocks/Hero";
import { LogoCarousel } from "@/components/Blocks/LogoCarousel";
import { FeatureSection } from "@/components/Blocks/FeatureSection";
import { TeamSection } from "@/components/Blocks/TeamSection";
import { TestimonialSection } from "@/components/Blocks/TestimonialSection";
import { PricingSection } from "@/components/Blocks/PricingSection";
import { FaqSection } from "@/components/Blocks/FaqSection";

export default function Home() {
  return (
    
      
        
        
        
        
        
        
        
      
    
  );
}

No dynamic imports, no lazy-loading config, no context providers wrapping everything. Each section is a completely self-contained component in components/Blocks/. None of them import from each other.

This decision came from watching how developers actually use shadcn templates. The first thing anyone does after cloning is delete the sections they don't need and reorder the ones they keep. With flat imports, removing the Team section is one deleted line. Reordering sections is moving one line. Adding a new section is creating a file and adding one import.

The alternative (a sections array, a renderer loop, a config file that controls order) sounds sophisticated. In practice, it adds indirection that makes the template harder to understand and slower to customize. Templates should be obvious, not impressive.

Lesson: in a template context, the simplest architecture is the correct architecture. The developer cloning your template isn't impressed by abstraction. They want to understand the code fast and change it faster.

Lesson 5: Staggered Animations Without Managing Individual Delays

The Hero section uses entrance animations where each element fades up sequentially: badge first, then heading, then subheading, then CTA. The naïve approach sets a different delay prop on each element manually. The correct approach uses staggerChildren:

// components/Blocks/Hero.tsx
"use client"
import { motion, type Variants } from "motion/react"

const containerVariants: Variants = {
  hidden: { opacity: 0 },
  visible: {
    opacity: 1,
    transition: {
      staggerChildren: 0.15,  // each child animates 150ms after the previous
      delayChildren: 0.1,
    },
  },
}

const fadeUpVariants: Variants = {
  hidden: { opacity: 0, y: 20 },
  visible: {
    opacity: 1,
    y: 0,
    transition: { duration: 0.5, ease: "easeOut" },
  },
}

const Hero = () => (
  
    
      {/* Badge */}
    
    
      AI Chatbot for Customer Support.
    
    
      {/* Subheading */}
    
    
      {/* CTA */}
    
  
)

The parent defines staggerChildren: 0.15. Every child with variants={fadeUpVariants} automatically inherits a 150ms offset from the previous child. Want to add a new element? Give it variants={fadeUpVariants} and the stagger chain extends automatically. No manually updated delay values.

The Features section uses scroll-triggered animations with a different easing:

// components/Blocks/FeatureSection.tsx

viewport={{ once: true }} fires the animation once when the element enters the viewport, not on every scroll pass. amount: 0.3 starts the animation when 30% of the element is visible, not when the full element is on screen. The cubic bezier [0.22, 1, 0.36, 1] is a fast-out-slow-in curve that feels physical rather than mechanical.

Quick note on the import: most of the core API is compatible, but motion/react isn't a straight drop-in rename of framer-motion. If you're upgrading an existing project, check the official migration guide before swapping the import. Layout animations, AnimatePresence behaviour, and some hooks changed.

Lesson: define animation variants at the parent level and use staggerChildren to orchestrate the sequence. Never set delay manually on individual elements — that creates a brittle list of numbers you have to update every time you add or remove an element. Let the parent handle timing; let children just declare what they animate to.

Lesson 6: CSS-Only Infinite Scroll — No Library Needed

The testimonials use a dual-row auto-scrolling marquee. The second row scrolls in reverse. There's no third-party marquee package. It's a small component built entirely on CSS animations defined in Tailwind v4's @theme block.

// components/ui/marquee.tsx
export function Marquee({
  reverse = false,
  pauseOnHover = false,
  vertical = false,
  children,
  repeat = 4,
  ...props
}) {
  return (
    
      {Array(repeat).fill(0).map((_, i) => (
        
          {children}
        
      ))}
    
  )
}

The repeat={4} prop renders the children 4 times side by side. As the CSS animation scrolls the container left, the repetitions create a seamless loop. By the time the first set has scrolled off screen, the second set is already in position.

group-hover:paused is Tailwind applying animation-play-state: paused when the parent has group class and is hovered. No onMouseEnter/onMouseLeave handlers or state, just pure CSS.

To customize the scroll speed without touching the component source, you override the CSS variable inline:


  {items.map(item => )}

[--duration:20s] is a Tailwind arbitrary property. It sets --duration directly on the element, which the animation reads via var(--duration). Speed customization without a prop, without touching the component.

Lesson: before reaching for a third-party animation package, check whether a CSS keyframe animation and a couple of Tailwind utilities can do the same job. A marquee, a fade loop, a pulsing skeleton — all of these are achievable with native CSS. Fewer dependencies means fewer breaking changes when the ecosystem moves.

Lesson 7: CSS Subgrid Solves Pricing Card Alignment Natively

The pricing section has three cards: Free, Pro, and Business. Each card has four rows: plan name, price, CTA button, and features list. The features list height varies between plans. Without CSS subgrid, the rows don't align across cards.

The common workaround is min-height on each row, or JavaScript that measures each card and sets explicit heights. Both approaches are fragile. Subgrid solves it in CSS:

// components/Blocks/PricingSection.tsx

  {plans.map((plan) => (
    
      {/* Plan name + description */}
      {/* Price */}
      {/* CTA button */}
      {/* Features list */}
    
  ))}

grid-rows-subgrid tells each card to participate in the parent grid's row tracks rather than creating its own. Each card spans 4 rows (row-span-4). The plan name row, price row, CTA row, and features row align across all three cards (regardless of content height) because they're all on the same row tracks.

Each card's row-span-4 reserves four rows in the parent's implicit grid. Because every card spans the same four shared row tracks, their internal rows align automatically even though the parent never declares explicit row heights.

CSS subgrid has been in all modern browsers since late 2023. There's no reason to reach for a JavaScript layout solution when the platform handles it.

Lesson: when you have a grid of cards where each card has multiple internal rows that need to align across columns, reach for grid-rows-subgrid before reaching for min-height or JavaScript. Define the number of rows each card spans with row-span-N, and the browser handles the rest.

Lesson 8: Inline SVGs Beat Image Libraries for Simple Logos

The logo carousel renders 12 brand logos: Shopify, Stripe, GitHub, Google, and others. The first instinct is to use a package like react-icons or simple-icons. I went a different direction: inline SVG paths stored as a plain TypeScript object.

// components/Blocks/LogoCarousel.tsx
const iconMap = {
  stripe: "M13.976 9.15c-2.172-.806...",
  github: "M12 .297c-6.63 0-12...",
  google: "M12.48 10.92v3.28h7.84...",
  // ...
} as const

const SimpleIcon = ({ iconSlug, size = 24 }: { iconSlug: string; size?: number }) => {
  const iconPath = iconMap[iconSlug as keyof typeof iconMap]
  return (
    
  )
}

The fill-black dark:fill-white class means every logo automatically inverts in dark mode: no separate dark mode logo assets, and no conditional rendering based on theme.

The carousel itself duplicates the logo array to create a seamless loop:

{/* First pass */}
{techCompanies.map((company, i) => )}
{/* Second pass — identical, creates the seamless loop */}
{techCompanies.map((company, i) => )}

The CSS animation (animate-logo-scroll) scrolls the container left. When the first pass disappears off the left edge, the second pass is already in position. The loop is seamless.

The trade-off: maintaining SVG paths manually is fine for a fixed set of logos. If you need a large dynamic icon set, reach for simple-icons or a proper icon library. For 12 brand logos that rarely change, this approach ships zero extra dependencies.

Lesson: match your tooling to your actual requirements. A logo carousel with a fixed set of brand logos doesn't need an icon library — it needs a TypeScript object and two Tailwind classes. Installing a package to solve a problem you could solve with 10 lines of code adds maintenance surface for no gain.

What I'd Do Differently

These are the three decisions I'd change if starting the template today.

1. Extract Animation Variants to a Shared File

containerVariants and fadeUpVariants are currently defined locally in both Hero.tsx and FeatureSection.tsx. If you want to change the global animation timing (say, reduce duration from 0.5s to 0.3s) you update two files. A shared lib/animations.ts exporting the standard variants would make global timing changes a one-line edit.

// lib/animations.ts
export const fadeUpVariants: Variants = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0, transition: { duration: 0.5, ease: "easeOut" } },
}

export const containerVariants: Variants = {
  hidden: { opacity: 0 },
  visible: { opacity: 1, transition: { staggerChildren: 0.15, delayChildren: 0.1 } },
}

2. Use Subgrid in the Features Section Too

The Features grid uses a border-based visual separation pattern — borders between cells create the grid appearance. It works, but the hover states have an inconsistency: the gradient hover overlay height varies slightly between cells in the same row because content heights differ. Subgrid would lock those row heights across cards the same way it does in the Pricing section.

3. Use `next/font` More Consistently

The layout loads both Geist and Inter font families. Inter is used via --font-sans. Geist is loaded but the geistSans.variable and geistMono.variable are applied to as className strings while Inter drives the actual font rendering through the CSS variable. The result is that Geist is loaded but not actually displayed. Cleaning this up could shave tens of kilobytes from the font payload — worth verifying in Lighthouse or the Network tab before deploying.

Summary

These are the five things from this build worth taking into your next project:

shadcn/ui's base-nova style runs on Base UI primitives. ARIA state drives visual state — no parallel JavaScript state needed.
Tailwind v4 moves theme config to CSS. All theme tokens, custom animations, and radius scales live in CSS via @theme inline. This is the right place for them.
OKLCH gives predictable dark mode contrast. Adjusting lightness in OKLCH actually changes perceived brightness. Hex and HSL don't guarantee this.
staggerChildren in motion/react eliminates manually managed animation delays. The parent orchestrates while the children just declare their animation variant.
CSS subgrid (grid-rows-subgrid) aligns card rows across columns natively. No JavaScript measurement, no fixed heights.

The full template is MIT-licensed and available at github.com/ShadcnDeck/chatdeck-shadcn-saas-landing-page-template. If it's useful, a star helps others find it.

What Happens During a Production Deployment? A Behind-the-Scenes Guide

Manish Shivanandhan — Mon, 03 Aug 2026 18:15:54 +0000

You push your code. A few minutes later, it is live for real users.

Between those two moments runs a long chain of machinery: builds, artefacts, migrations, health checks, traffic shifts. Every production engineer depends on that chain, and many teams still build and operate it themselves.

Deployment infrastructure has quietly become operational overhead. It started as a technical necessity, something every team had to assemble because nothing else existed.

Today it is a second system your engineers maintain alongside the product, consuming on-call rotations, sprint capacity, and 2 a.m. attention that could go somewhere better.

In this article, we'll walk through each stage of a real production deployment: the build, the artefact it produces, database migrations, health checks, rolling updates, and rollbacks. Along the way, we'll look at why platform-as-a-service (PaaS) tools handle most of these steps for you, and what it costs a team to keep handling them itself.

The Build: Turning Code into Something That Can Run
The Artefact: One Version, Frozen in Time
Database Migrations: The Riskiest Step
Health Checks: Proving the New Version Is Alive
Rolling Updates: Replacing the Plane's Engine Mid-Flight
Rollbacks: The Escape Hatch
When You Don't Need a PaaS
Should You Still Be Running This Yourself?

The Build: Turning Code into Something That Can Run

A deployment does not ship your source code as-is. It ships the result of a build. The build stage takes your code and turns it into something a server can run.

What this looks like depends on your stack. A Java or Go project gets compiled into a binary. A JavaScript front end gets bundled and minified. A Python app gets its dependencies resolved and pinned. In most modern setups, all of this gets packed into a container image, which is a frozen snapshot of your app plus everything it needs to run.

The build stage also runs your tests. Unit tests, linting, and security scans all happen here. If any of them fail, the deployment stops before it can touch production. This is the cheapest place to catch a bug. A failed build costs you a few minutes. A failed deployment can cost you customers.

Teams that run their own pipelines spend real effort here. They maintain build servers, cache dependencies, and debug flaky test runners.

None of that work ships a feature. It is pure upkeep, and it never ends. A PaaS bakes this whole stage into the platform. You push code, and the platform detects your language, builds it the same way every time, and fails fast when something is wrong. The build still happens. Your engineers just stop paying for it in hours.

The Artefact: One Version, Frozen in Time

The output of a build is called an artefact. It might be a container image, a compiled binary, or a zipped bundle. Whatever the format, the artefact has one job: to be exact. It represents one precise version of your app, frozen at one point in time.

This matters more than it sounds. The artefact that passed your tests must be the exact same one that reaches production. If you rebuild between testing and shipping, you risk shipping something slightly different. A dependency may have updated. A build flag may have changed. "It worked in staging" often means "we built it twice and got two different results."

Good pipelines build once and promote the same artefact through every stage. Artefacts get versioned and stored in a registry, so any version can be pulled and run again later. That stored history is also what makes rollbacks possible, which we will get to soon.

On a PaaS, artefact handling is standard practice by default. Every deploy produces a numbered release. The platform stores it, tracks it, and can restore it. You do not have to design a registry strategy, write promotion scripts, or assign an engineer to own them. The discipline is built in.

Database Migrations: The Riskiest Step

Before new code goes live, the database often has to change with it. Maybe the new version needs a new column or a new table. These changes are called migrations, and they are the most dangerous part of most deployments.

Why? Code is easy to replace. Data is not. If you deploy a bad code version, you can swap it out. If a migration corrupts or drops data, there may be no clean way back. Migrations also create a tricky window of time. For a few minutes, old code and new code may run against the same database at once. Both versions have to work with the schema during that window.

The safe pattern is to make migrations backwards-compatible. Add the new column first, deploy code that can handle both shapes, then clean up the old column in a later release. It takes more steps, but each step is safe on its own.

A PaaS cannot write your migrations for you. No tool can know what your data means. But a good platform gives migrations a defined place in the release process, runs them in order, and logs exactly what ran and when. That structure prevents the classic failure where someone runs a migration by hand and forgets to tell the team.

Health Checks: Proving the New Version Is Alive

Once the new version starts, the platform does not just trust it. It checks. A health check is a small endpoint in your app, often just a route that returns "OK." The platform calls it over and over. If the app answers, it is considered healthy. If it does not, the platform assumes something is wrong.

There are usually two kinds of checks. A readiness check asks, "Are you ready to receive traffic?" A liveness check asks, "Are you still working, or should I restart you?" The difference matters. An app can be alive but not ready, such as when it is still warming up a cache.

Health checks are the gatekeepers of a deployment. No traffic reaches a new version until it proves it can handle requests. Without them, you would be routing real users to an app that might still be crashing on startup.

Every serious PaaS runs health checks automatically. You define the endpoint, and the platform handles the polling, the timeouts, and the decisions. Teams that build this themselves tune all of those settings by hand, and they usually learn the right values through painful trial and error. That tuition is paid in engineering time, on a problem the industry solved years ago.

Rolling Updates: Replacing the Plane's Engine Mid-Flight

Here is the hard part. Your old version is serving live traffic right now. You need to replace it without dropping a single request. The most common answer is a rolling update.

It works like this. Say you have four copies of your app running. The platform starts one copy of the new version and waits for its health checks to pass. Then it shifts a slice of traffic to it and shuts down one old copy. It repeats this, one copy at a time, until only the new version remains. Users never notice, because at every moment there are enough healthy copies to serve everyone.

Some teams use variations of this idea. A blue-green deployment runs the full new version beside the old one, then flips all traffic at once. A canary release sends a tiny share of users to the new version first, watching for errors before going wider.

Doing this by hand means writing orchestration logic, managing load balancer rules, and handling every edge case where a step fails halfway. That is months of engineering effort to build and a permanent tax to maintain, all for behavior a PaaS ships as the default. On a platform, you get zero-downtime releases out of the box, not as a project your team has to staff.

Rollbacks: The Escape Hatch

Sometimes the new version passes every check and still breaks something real. An error rate climbs. A page loads blank. Now speed matters more than anything, and the fastest fix is rarely a new patch. It is a rollback: redeploying the previous artefact that you already know works.

This is why frozen, versioned artefacts are so important. A rollback is only fast if the old version is stored, tested, and ready to run. Teams that rebuild from an old commit under pressure are gambling at the worst possible time.

On most PaaS platforms, a rollback is one command or one click. The platform keeps your release history and can restore any previous version in seconds. That single feature has saved more on-call engineers' nights than perhaps any other.

When You Don't Need a PaaS

The case for handing deployment to a platform is strong, but it isn't universal. There are teams for whom owning the pipeline is not overhead; it is a deliberate and justified engineering decision.

When Compliance Demands It

Regulated industries like finance, healthcare, government, often operate under requirements that a standard PaaS cannot satisfy out of the box. Data residency rules may dictate exactly which physical infrastructure your builds touch. Audit requirements may demand a level of provenance and access logging that a managed platform doesn't expose.

Security controls may need to extend into the build environment itself, not just the runtime. In these contexts, the cost of owning the pipeline is real, but it is the cost of operating in that industry.

When Deployment is Your Product

If your company sells deployment infrastructure, a CI/CD platform, a release orchestration tool, an internal developer platform, then your pipeline is not overhead at all. It is the product.

The engineers maintaining it are doing product work, not distraction work. The same applies to platform engineering teams at large organizations whose explicit charter is to build and own the deployment layer for dozens of other internal teams. In both cases, the question of "why are we running this ourselves" has an obvious answer: because this is what we do.

When Your Infrastructure is Genuinely Unusual

Most PaaS platforms are optimized for stateless web services and standard container workloads. If your system falls outside that envelope, GPU clusters, real-time systems with strict latency requirements, hybrid on-premise and cloud deployments, hardware-in-the-loop testing, a general-purpose platform may simply not fit.

Shoehorning an unusual workload into a PaaS often produces more friction than building narrow, purpose-built deployment tooling around the specific constraints you actually have.

The common thread across all three cases is specificity. The teams that are right to own their pipelines can usually state clearly why a platform doesn't fit. If the answer is "we've always done it this way" or "we like having control," that's worth questioning. If the answer is "our compliance requirements mandate X" or "we sell this," that's a reason.

Should You Still Be Running This Yourself?

A PaaS does not make any of these steps disappear. The build still runs. Artefacts still get stored. Migrations still execute, health checks still poll, and traffic still shifts one copy at a time. Abstracting these mechanics does not eliminate them. It standardizes them, and pushes their maintenance onto a team whose entire product is deployment.

That is the question every product team should now ask plainly: why are we still building and operating this machinery ourselves? A decade ago, a custom pipeline was unavoidable. Today it is a choice, and for most teams it is the wrong one. Every hour spent debugging a flaky build agent, tuning a health check timeout, or patching orchestration scripts is an hour taken from the product your customers actually pay for. The pipeline does not differentiate you. It cannot. Your competitors' deploys work the same way yours do.

Know how the chain works, because on-call at 2 a.m. demands it. But knowing how it works is not a reason to own it. "We built our own deployment system" is not a badge of honor anymore. It is an admission that your team maintains a second product with no customers. Unless deployment infrastructure is your business, hand the machinery to a platform, and put your engineers back on the work only they can do.

Hope you enjoyed this article. You can connect with me on LinkedIn.

How to Create a Marketing Landing Page Using shadcn/ui

Vaibhav Gupta — Fri, 31 Jul 2026 11:01:41 +0000

Most marketing landing pages start with the same problem: you're staring at a blank screen and rebuilding sections you've already created countless times.

A hero section, feature grid, testimonials, pricing, FAQ, and footer are common building blocks, yet developers often spend hours recreating them for every new project.

In this guide, you'll learn how to build a modern marketing landing page using Next.js, shadcn/ui, Tailwind CSS, and reusable Shadcn blocks. Instead of building every section from scratch, you'll assemble a production-ready page, customize it to match your brand, and finish with a foundation that's ready for real-world projects.

Prerequisites
What Are We Building?
Project Setup with Base UI Using the Shadcn Preset
Two Ways to Build Your Marketing Landing Page
Option 1: Build Using the CLI
Option 2: Build Using the MCP Server
How to Optimize Your Landing Page
How to Expand Your Marketing Website
Live Preview:
Conclusion

Prerequisites

Before you start, make sure you have:

Node.js 18 or higher installed
shadcn/ui initialized in your project (npx shadcn@latest init)
Basic knowledge of React and TypeScript

If you haven't initialized shadcn/ui yet, run npx shadcn@latest init in your project root and follow the prompts before continuing.

What Are We Building?

In this tutorial, we'll build a modern marketing landing page using production-ready blocks from Shadcn Space. Instead of designing and developing every section from scratch, we'll assemble a complete landing page using reusable shadcn/ui blocks and customize them to fit our brand and product.

You can use the same approach to create landing pages for SaaS products, AI tools, startups, agencies, developer tools, portfolios, and many other types of websites. Since every block is built with React, Tailwind CSS, and shadcn/ui, you have full control over the code and can easily modify the content, layout, and styling.

Why Build with Shadcn Space?

Creating a professional marketing website typically involves designing multiple sections that work together to tell your product's story and guide visitors to take action.

But instead of building every section from scratch, you can start with production-ready blocks that are easy to customize.

This lets you build marketing websites faster with reusable blocks (and you can also mix and match blocks to create unique page layouts). It also gives you full ownership of your clean React and Tailwind CSS code. And overall, you save development time without sacrificing flexibility.

Sections We'll Build

We'll build our marketing landing page using the following sections:

Hero section with a compelling headline, call-to-action, and trusted-by logos.
Features section to highlight your product's key capabilities.
Product Showcase & Benefits section to demonstrate your product and communicate its value.
Testimonials section to build credibility with customer feedback.
Pricing section to present your plans clearly.
FAQ section answers common questions and reduces friction.
Call-to-Action section to encourage visitors to get started.
Footer with navigation and important links.

Final Page Structure

Our landing page will have this structure:


  {/* 1. Hero section + Trusted by / Logo cloud */}
  

  {/* 2. Features section */}
  

  {/* 3. Product showcase & Benefits */}
  

  {/* 4. Testimonials */}
  

  {/* 5. Pricing section */}
  

  {/* 6. FAQ section */}
  

  {/* 7. Call-to-action section */}
  

  {/* Footer */}

Each section will be installed from the Shadcn Space registry and customized directly inside our project. By the end of this tutorial, you'll have a fully responsive marketing landing page built with Next.js, Tailwind CSS, and shadcn/ui that you can adapt for your own product or business.

Project Setup with Base UI Using the Shadcn Preset

Since Shadcn Space blocks are built using Base UI primitives, we'll create our project using the Base UI preset instead of the default Radix setup.

This ensures that our landing page uses the same foundation as the blocks we're going to install.

1. Create the Project with Base UI

Run the following command:

pnpm dlx shadcn@latest init --preset b0 --template next

This command does a few important things:

Creates a Next.js project
Configures Tailwind CSS
Sets up Base UI as the component foundation
Uses the Nova style preset
Configures Lucide icons
Uses Inter font
Applies neutral theme tokens

You now have a Base UI-powered Next.js project ready for building your landing page.

2. Add the Shadcn Space Registry

Open your components.json and add the following registry configuration:

{
  "registries": {
    "@shadcn-space": {
      "url": "https://shadcnspace.com/r/{name}.json",
    }
  }
}

This tells the CLI where to fetch components and blocks from the registry.

For more information about how to use it in your project, check out the docs.

Two Ways to Build Your Marketing Landing Page

Now that your project is set up with shadcn/ui, it's time to start building the marketing landing page.

You can install production-ready blocks directly into your project in two different ways:

Using the CLI
Using the MCP Server inside your AI-powered editor

Both approaches install the actual React and Tailwind CSS source code into your project, giving you complete control over customization. The only difference is how you discover and install the blocks.

Option 1: Build Using the CLI

The CLI is the fastest way to browse the registry and install individual blocks into your project. It gives you full control over which sections you want to use and how you customize them.

Step 1: Browse Marketing Blocks

Visit the block registry and explore the available marketing blocks.

Let's review the sections we'll use for this tutorial:

Hero section with a call-to-action and trusted-by logos
Features section
Product showcase & benefits section
Testimonials section
Pricing section
FAQ section
Call-to-action section
Footer

Choose the blocks that best match the design and style of your website. Since every block is fully customizable, you can easily update the content, colors, spacing, and layout to match your brand.

In the following sections, we'll install each block and customize them.

Step 2: Install Selected Blocks

Once you find a block you like, install it using the CLI:

npx shadcn@latest add @shadcn-space/{block-name}

Each command downloads the block, places it inside components/shadcn-space/blocks, and installs the required dependencies.

Now your folder might look like this:

components/
  shadcn-space/
    blocks/
      about-us-section-01/
      hero-01/
      features-01/
      pricing-01/
      testimonial-01/
      faq-01/
      cta-01/
      footer-01/

Note: I've used the first block from each section in this tutorial. You can choose any other shadcn block that suits best according to your needs.

Step 3: Add a Hero Section

Every great marketing landing page starts with a strong hero section. It's the first thing visitors see, so it should clearly communicate what your product does, who it's for, and encourage users to take action.

Instead of building the section from scratch, we'll install a production-ready Hero block and customize it to match our landing page.

1. Install the Hero Block

Run the following CLI command to add the Hero block to your project:

npx shadcn@latest add @shadcn-space/hero-01

The CLI will automatically download the Hero block source code, add the component to your project, and install any required dependencies.

After the installation completes, you should see the following directory structure:

components/
  shadcn-space/
    blocks/
      hero-01/
        index.tsx

You can now open the component and customize the heading, description, call-to-action buttons, images, and other content to match your product and branding.

2. Understand the Hero Block Structure

Once the installation is complete, open the Hero block located at:

components/shadcn-space/blocks/hero-01/index.tsx

You'll see a component similar to the following:

import HeroSection from "@/components/shadcn-space/blocks/hero-01/hero";
import type { NavigationSection } from "@/components/shadcn-space/blocks/hero-01/header";
import Header from "@/components/shadcn-space/blocks/hero-01/header";
import BrandSlider, { BrandList } from "@/components/shadcn-space/blocks/hero-01/brand-slider";
import type { AvatarList } from "@/components/shadcn-space/blocks/hero-01/hero";

export default function AgencyHeroSection() {
  const avatarList: AvatarList[] = [...];
  const navigationData: NavigationSection[] = [...];
  const brandList: BrandList[] = [...];

  return (
    
      
      
        
        
      
    
  );
}

What Should You Notice?

Before making any changes, take a moment to understand how the block is organized. Rather than being a single large component, it's composed of smaller, reusable components that work together.

In this example:

The Header component renders the navigation and receives its menu items through the navigationData array.
The HeroSection component contains the main headline, description, call-to-action buttons, and social proof, while the avatarList provides the data displayed in the hero.
The BrandSlider component displays the company logos using the brandList array.

This separation keeps the code modular and makes each part of the landing page easier to customize or replace independently.

Why This Matters?

Because the block is copied directly into your project, you're working with standard React components instead of a compiled package. Every file is fully editable, allowing you to understand how the section is built and modify it to suit your own requirements.

For example, you can update the navigation links, replace the placeholder content with your own branding, add additional sections, integrate custom functionality, or adjust the styling using Tailwind CSS classes. Since everything lives inside your codebase, you're free to restructure the component however you like without being locked into predefined APIs or abstractions.

3. Render the Hero Section

Now that the Hero block has been installed, it's time to display it on the page.

Import the component into your app/page.tsx file:

import AgencyHeroSection from "@/components/shadcn-space/blocks/hero-01";

export default function Page() {
  return (
    
  );
}

Save the file and start your development server if it isn't already running. When you open the application in your browser, you'll see the Hero section rendered as the first part of your marketing landing page.

With the Hero section in place, we've completed the first building block of our landing page. Next, we'll continue by adding the remaining sections to create a complete marketing website.

Install the Remaining Blocks

Now that you've added and rendered the Hero section, let's install the remaining blocks required for our marketing landing page.

Run the following command to install all the remaining sections at once:

npx shadcn@latest add @shadcn-space/feature-01 @shadcn-space/about-us-section-01 @shadcn-space/testimonial-01 @shadcn-space/pricing-01 @shadcn-space/faq-01 @shadcn-space/cta-01  @shadcn-space/footer-01

Note: If you're using Windows Command Prompt or PowerShell, run the command on a single line instead of using \ for line continuation.

After the installation is complete, update your app/page.tsx by importing the newly added blocks and rendering them in the following order:

import AgencyHeroSection from "@/components/shadcn-space/blocks/hero-01";
import AboutAndStats01 from "@/components/shadcn-space/blocks/about-us-01";
import Feature01 from "@/components/shadcn-space/blocks/feature-01";
import Pricing from "@/components/shadcn-space/blocks/pricing-01/pricing";
import Testimonials from "@/components/shadcn-space/blocks/testimonial-01/testimonial";
import Faq from "@/components/shadcn-space/blocks/faq-01/faq";
import CTA from "@/components/shadcn-space/blocks/cta-01/cta";
import Footer from "@/components/shadcn-space/blocks/footer-01/footer";


export const metadata = {
  title: "Acme Agency – Innovative Digital Solutions",
  description:
    "We craft immersive digital experiences for bold brands. Explore our services, pricing, and success stories.",
};


export default function Page() {
  return (
    
      {/* 1. Hero section + Trusted by / logo cloud */}
      


      {/* 2. Features section */}
      


      {/* 3. Product showcase & Benefits section (Using About/Stats as a placeholder for these) */}
      


      {/* 4. Testimonials */}
      


      {/* 5. Pricing section */}
      


      {/* 6. FAQ section */}
      


      {/* 7. Call-to-action section */}
      


      {/* Footer */}
      
    
  );
}

That's it! Your complete marketing landing page is now assembled. You can start customizing the content, images, colors, and layout of each section to match your product and brand.

Customize the Marketing Landing Page

At this point, the overall structure of your marketing landing page is complete. The next step is to personalize each section so it reflects your product, brand, and messaging instead of the default placeholder content.

One of the biggest advantages of working with reusable React components is that every section can be customized independently. You can update the content, replace images, adjust layouts, and refine the styling without rebuilding the page from scratch.

The following examples show how the default blocks can be transformed into a polished marketing website.

Customize the Hero Section

The Hero section is the first thing visitors see, so it's the most important place to communicate your product's value. Replace the placeholder headline, supporting text, call-to-action buttons, and trusted brand logos with content that represents your own business.

Before:

After:

Notice how the customized version immediately establishes the product's identity through updated messaging, branding, imagery, and call-to-action buttons.

Customize the Features Section

The Features section should explain what your product offers and why it stands out. Replace the sample feature cards with capabilities that highlight your product's most valuable functionality.

Before:

After:

Updating the feature titles, descriptions, and icons makes the section more relevant to your audience while reinforcing your product's key selling points.

Customize the Pricing Section

Your pricing section should clearly communicate the plans you offer and help visitors choose the option that best fits their needs. Replace the default plans, pricing, feature lists, and button labels with information that matches your business model.

Before:

After:

A customized pricing section builds trust by presenting accurate information while making it easier for potential customers to compare plans.

Customize the FAQ Section

The FAQ section is a great opportunity to answer common questions before visitors contact your team. Replace the placeholder questions with answers related to your product, pricing, integrations, support, or onboarding process.

Before:

After:

Tailoring the FAQ to your product helps reduce uncertainty, improves the user experience, and can answer many questions before a customer reaches out.

The Result

With just a few content updates, the default blocks evolve into a professional marketing landing page tailored to your brand. Since every section is built with reusable React components, you can continue refining the design, adjusting layouts, and adding new content as your product grows without changing the overall page structure.

Option 2: Build Using the MCP Server

If you prefer a faster workflow, you can use the MCP Server to generate your landing page directly inside your editor. Instead of manually browsing and installing individual blocks, you simply describe the page you want to build, and the MCP Server assembles an initial version for you.

The MCP Server works with supported editors like Antigravity, VS Code, Cursor, Windsurf, and other MCP-compatible editors.

Step 1: Install the MCP Server

Quick Installation:

The fastest way to get started. Choose your package manager and run the command corresponding to your client:

For Claude Code:

claude mcp add shadcnspace-mcp -- npx -y shadcnspace-mcp@latest

For Others:

npx shadcnspace-cli install

Replace with cursor, antigravity, vscode, or windsurf.

Manual Installation For VS Code:

{
  "servers": {
    "shadcnspace-mcp": {
      "command": "npx",
      "args": ["-y", "shadcnspace-mcp@latest"]
    }
  }
}

Open .vscode/mcp.json.
Click Start next to the Shadcn Space MCP server

For a detailed guide, follow the MCP Server documentation to install it for your preferred editor.

Once the installation is complete, restart your editor to enable the MCP connection.

Step 2: Open the AI Chat

Open the AI chat panel inside your editor and describe the landing page you'd like to create.

For example:

Create a modern marketing landing page for an AI SaaS product.

Use Shadcn Space blocks and include:

- Hero section
- Features section
- Product showcase & benefits
- Testimonials
- Pricing
- FAQ
- Call-to-action
- Footer

Use a clean, modern, and responsive design.

Feel free to replace the product description with your own and customize as you like.

Step 3: Generate the Landing Page

After receiving your prompt, the MCP Server analyzes your requirements and selects the most suitable blocks for your landing page. It automatically assembles the page using a combination of reusable sections, giving you a working layout in just a few moments.

The generated sections are added directly to your project as standard React components. Since everything is real source code, you can customize every part of the page: update the content, replace images, modify the layout, adjust spacing, or restyle components using Tailwind CSS.

The MCP Server simply speeds up the initial setup, while giving you complete control over the final implementation.

How to Optimize Your Landing Page

Building a visually appealing landing page is only the first step. Before publishing your website, it's worth spending some time optimizing it for performance, search engines, and user experience.

A fast, responsive landing page not only feels more polished but also helps improve engagement and conversion rates. Fortunately, Next.js provides several built-in features that make these optimizations straightforward.

Optimize Images with Next.js

Images are often the largest assets on a marketing website, so optimizing them can significantly improve loading performance. If you're using Next.js, prefer the built-in next/image component instead of the standard HTML image tag. It automatically serves appropriately sized images, supports modern image formats, and reduces layout shifts as the page loads.

Before adding screenshots or illustrations to your project, make sure they're compressed and sized appropriately. Well-optimized images create a smoother browsing experience across desktop and mobile devices while also contributing to better Core Web Vitals.

Improve SEO for Your Landing Page

A well-designed landing page is only effective if people can discover it. Search engine optimization starts with creating meaningful content that clearly communicates what your product offers. Choose a descriptive page title, write a concise meta description, and organize your content using logical headings.

Your primary keyword should appear naturally throughout the page without forcing it into every paragraph. Focus on writing for your audience first, then structure the content in a way that search engines can easily understand. Combining valuable content with a clear page hierarchy gives your landing page the best chance of ranking for relevant searches.

Add Metadata and Open Graph Images

When someone shares your landing page on social media or in a messaging application, the preview is generated from your page's metadata. Configuring Open Graph and Twitter metadata allows you to control the title, description, and preview image that appear when your website is shared.

A custom preview image that reflects your branding makes your links look more professional and can encourage more people to click through. Taking a few minutes to configure these settings helps create a more polished experience whenever your content is shared online.

Optimize Performance

Performance plays a major role in how visitors perceive your website. A page that loads quickly feels more responsive and encourages users to continue exploring your content. As you customize your landing page, keep unnecessary JavaScript to a minimum, optimize static assets, and avoid loading resources that aren't immediately needed.

Even small improvements, such as reducing image sizes or simplifying animations, can noticeably improve loading speed. Before deploying your project, test the page under different network conditions to ensure it performs well for all visitors.

Improve Core Web Vitals

Core Web Vitals are Google's metrics for measuring real-world user experience. They evaluate how quickly your main content appears, how responsive the page feels during interactions, and whether elements remain stable as the page loads. Monitoring these metrics throughout development helps identify potential issues before they affect users.

Tools such as Lighthouse and PageSpeed Insights provide detailed reports that can help you improve loading performance and responsiveness. A landing page with strong Core Web Vitals not only creates a better experience for visitors but can also contribute to improved search rankings.

How to Expand Your Marketing Website

A landing page is often just the beginning of a complete marketing website. As your product grows, you'll likely need additional pages that provide more information, improve navigation, and create a better experience for your visitors. Common additions include Blog, Blog Details, Pricing, FAQ, Changelog, Contact, Integration, Error, and About Us pages.

Building these pages with a consistent design system helps maintain a unified look and feel across your entire website while reducing development time. Reusing layouts and components also makes your project easier to maintain as it evolves.

If you're looking to expand your website beyond a single landing page, explore the collection of production-ready Shadcn website pages, built with React, Next.js, Tailwind CSS, and shadcn/ui.

Live Preview:

Conclusion

In this tutorial, we built a complete marketing landing page using Next.js, shadcn/ui, Tailwind CSS, and reusable Shadcn Space blocks. Starting from a fresh project, we assembled a production-ready page by combining sections such as the Hero, Features, Product Showcase, Testimonials, Pricing, FAQ, Call-to-Action, and Footer.

Because every block is added as standard React source code, you're free to customize the content, layout, styling, and functionality to match your own product and branding. Whether you're building a SaaS application, a startup website, an AI product, an agency site, or a developer tool, the same approach can be adapted to your requirements.

A marketing landing page is just the foundation of your online presence. As your product grows, you can continue expanding your website with additional marketing pages while maintaining a consistent design system and development workflow.

I hope this guide has helped you understand how to quickly build a modern, responsive marketing landing page using reusable components. Feel free to experiment with different block combinations, personalize the design, and create a website that best represents your product.

Appreciation: I wrote this article with the help of Mihir Koshti (Sr. Full Stack Developer) – Connect on LinkedIn.

How to Build a Browser-Based PDF Blur Tool Using JavaScript

Bhavin Sheth — Fri, 24 Jul 2026 20:44:56 +0000

Many PDF documents contain information that shouldn't be shared publicly. Personal details, financial figures, signatures, addresses, account numbers, employee information, or confidential business data often need to be hidden before a file is sent to someone else.

A PDF Blur Tool makes this process simple. Instead of permanently removing content, it places a blur effect over selected areas of a PDF so sensitive information becomes difficult to read while the rest of the document remains unchanged.

In this tutorial, you'll build a browser-based PDF Blur Tool using JavaScript. Users will be able to upload a PDF, preview every page, draw blur boxes over sensitive content, adjust the blur intensity, apply the blur to selected pages, preview the final result, and download the processed PDF, all without uploading files to a server.

We'll use PDF.js to render PDF pages inside the browser, HTML Canvas to create and manage blur regions, and PDF-lib to generate the final blurred PDF.

By the end of this tutorial, you'll have a fully functional client-side PDF editing tool similar to the one available on my site, AllInOneTools.

What This PDF Blur Tool Does and How It Works
Project Setup
Creating the HTML Layout
Uploading and Previewing PDFs
Creating Blur Regions
Applying Blur to Pages
Generating the Final PDF
Previewing the Result
Renaming and Downloading
Demo: How the PDF Blur Tool Works
Performance Tips
Common Mistakes
Conclusion

What This PDF Blur Tool Does and How It Works

A PDF Blur Tool helps protect sensitive information before a document is shared. Instead of editing or deleting the original content, it applies a visual blur effect over selected areas so confidential information becomes unreadable while the rest of the document remains unchanged.

This approach is useful for hiding personal details, financial information, account numbers, signatures, addresses, faces, or any other private content that shouldn't be visible in the final document.

In this project, users can upload a PDF directly from their browser, preview every page, and draw one or more blur regions over the areas they want to hide. The tool also allows users to adjust the blur intensity, blur either selected areas or entire pages, apply the effect to the current page, all pages, or specific page ranges, preview the completed document, rename the output file, and download the final PDF.

Because everything runs inside the browser, no files are uploaded to a server, helping maintain document privacy.

Behind the scenes, the application first renders each PDF page onto an HTML canvas using PDF.js. Rather than modifying the original PDF immediately, it records the position, size, page number, and blur intensity for every blur region that the user creates.

When the user clicks Apply & Finalize, those stored regions are converted from browser coordinates into actual PDF page coordinates. The selected blur effect is then applied to the rendered page, and PDF-lib generates a new PDF containing the blurred content while preserving the rest of the document.

This workflow provides an interactive editing experience while keeping the original PDF unchanged until the final document is generated.

For example, each blur region can be represented as an object like this:

const blurRegion = {

    page: 2,

    x: 180,

    y: 240,

    width: 260,

    height: 90,

    intensity: 6

};

Each object stores all the information required to recreate the blur effect during the final PDF generation process.

Project Setup

Before writing any code, let's create a simple project structure for our PDF Blur Tool.

We'll use plain HTML, CSS, and JavaScript, along with two libraries:

PDF.js for rendering PDF pages inside the browser.
PDF-lib for generating the final blurred PDF.

Our project structure looks like this:

pdf-blur-tool/

│── index.html
│── style.css
│── script.js
│── pdf.worker.min.js
│── assets/

Keeping the project simple makes it easier to understand how each part works.

Add PDF.js and PDF-lib before loading your own JavaScript.

Configure the PDF worker.

pdfjsLib.GlobalWorkerOptions.workerSrc =
    "pdf.worker.min.js";

The worker processes PDF rendering in a background thread, helping keep the interface responsive while pages are rendered.

Creating the HTML Layout

The application consists of four main sections:

Upload area
PDF preview
Blur settings panel
Final download section

Create the basic layout:

Initially, only the upload section is visible.

After a PDF is selected, the editor becomes visible.

Selecting DOM Elements

Create references to the elements used throughout the application.

const uploadSection =
    document.getElementById(
        "uploadSection"
    );

const editorSection =
    document.getElementById(
        "editorSection"
    );

const resultSection =
    document.getElementById(
        "resultSection"
    );

const fileInput =
    document.getElementById(
        "pdfInput"
    );

const pdfCanvas =
    document.getElementById(
        "pdfCanvas"
    );

const canvasContext =
    pdfCanvas.getContext("2d");

These references allow the application to switch between the upload, editing, and download stages.

Uploading and Previewing PDFs

The upload section accepts both drag-and-drop and traditional file selection.

When a PDF is chosen, verify that it's actually a PDF before continuing.

async function handlePdfUpload(
    file
) {

    if (
        !file ||
        file.type !==
        "application/pdf"
    ) {

        alert(
            "Please select a PDF file."
        );

        return;

    }

    await loadPdf(file);

}

If validation succeeds, the document is loaded into memory.

Reading the PDF

Use the File API to convert the uploaded file into an ArrayBuffer.

async function loadPdf(
    file
) {

    const bytes =
        await file.arrayBuffer();

    pdfDocument =
        await pdfjsLib
            .getDocument({
                data: bytes
            })
            .promise;

    currentPage = 1;

    await renderPage(
        currentPage
    );

}

The uploaded bytes will also be reused later when generating the blurred PDF.

Rendering the First Page

PDF.js renders each page onto an HTML canvas.

Start by retrieving the requested page.

async function renderPage(
    pageNumber
) {

    const page =
        await pdfDocument
            .getPage(
                pageNumber
            );

    const viewport =
        page.getViewport({
            scale: 1.5
        });

Resize the canvas to match the page dimensions.

pdfCanvas.width =
    viewport.width;

pdfCanvas.height =
    viewport.height;

Render the page.

await page.render({

    canvasContext,

    viewport

}).promise;

After rendering finishes, the PDF page becomes visible inside the editor.

Most PDF documents contain multiple pages.

Allow users to move between pages using Previous and Next buttons.

let currentPage = 1;

let pdfDocument = null;

Move to the previous page.

previousButton
.addEventListener(
    "click",
    async () => {

        if (
            currentPage === 1
        ) {

            return;

        }

        currentPage--;

        await renderPage(
            currentPage
        );

    }
);

Move to the next page.

nextButton
.addEventListener(
    "click",
    async () => {

        if (
            currentPage ===
            pdfDocument.numPages
        ) {

            return;

        }

        currentPage++;

        await renderPage(
            currentPage
        );

    }
);

Update the page counter whenever the current page changes.

pageIndicator.textContent =
    `Page ${currentPage} of ${pdfDocument.numPages}`;

This provides users with clear feedback while navigating large PDF documents.

Preparing for Blur Editing

Once the current page is rendered, the application prepares a transparent layer above the PDF canvas.

This overlay captures mouse interactions without modifying the original page preview.

Create the overlay.

Match its size to the PDF preview.

overlayCanvas.width =
    pdfCanvas.width;

overlayCanvas.height =
    pdfCanvas.height;

Later in the tutorial, this overlay will allow users to draw blur regions while keeping the underlying PDF page untouched.

Showing the Editor

After the first page finishes rendering, switch from the upload screen to the editor interface.

uploadSection.hidden =
    true;

editorSection.hidden =
    false;

Users can now preview the document, navigate between pages, and begin selecting areas that should be blurred.

Creating Blur Regions

Now that the PDF preview is working, we can build the most important feature of the application: allowing users to blur sensitive information.

Instead of editing the PDF immediately, users first draw one or more blur regions over the page preview.

Each region stores its own position, size, and blur intensity. These regions are later converted into actual PDF coordinates during final processing.

Creating the Blur Area Object

Every blur region is represented as a JavaScript object.

For example:

const blurArea = {

    page: currentPage,

    x: 0,

    y: 0,

    width: 0,

    height: 0,

    intensity: 6

};

Rather than modifying the PDF immediately, the application simply keeps track of these objects until the user clicks Apply & Finalize.

Storing Multiple Blur Regions

Users often need to hide more than one piece of information.

Store all blur areas inside an array.

const blurAreas = [];

Whenever a new blur box is created, push it into the array.

blurAreas.push({

    page: currentPage,

    x,

    y,

    width,

    height,

    intensity:
        blurIntensity

});

This makes it easy to redraw, edit, or remove individual blur regions later.

Starting a Blur Selection

The transparent overlay canvas captures mouse interactions.

When the user presses the mouse button, record the starting position.

let isDrawing = false;

let startX = 0;

let startY = 0;

overlayCanvas
.addEventListener(
    "mousedown",
    event => {

        isDrawing = true;

        startX = event.offsetX;

        startY = event.offsetY;

    }
);

The blur rectangle begins at this point.

Drawing the Blur Rectangle

As the mouse moves, update the rectangle dimensions.

overlayCanvas
.addEventListener(
    "mousemove",
    event => {

        if (
            !isDrawing
        ) {

            return;

        }

        drawPreviewBox(

            startX,

            startY,

            event.offsetX,

            event.offsetY

        );

    }
);

The preview updates continuously while the user drags the mouse.

Finishing the Selection

When the mouse button is released, save the completed blur region.

overlayCanvas
.addEventListener(
    "mouseup",
    event => {

        isDrawing = false;

        blurAreas.push({

            page:
                currentPage,

            x:
                startX,

            y:
                startY,

            width:
                event.offsetX -
                startX,

            height:
                event.offsetY -
                startY,

            intensity:
                blurIntensity

        });

        redrawBlurAreas();

        updateBlurList();

    }
);

Each blur region becomes part of the current editing session.

Drawing Existing Blur Areas

Whenever the page changes or a blur region is added, redraw every blur box.

function redrawBlurAreas() {

    overlayContext.clearRect(

        0,

        0,

        overlayCanvas.width,

        overlayCanvas.height

    );

    blurAreas

        .filter(

            area =>

                area.page ===
                currentPage

        )

        .forEach(

            drawBlurArea

        );

}

This ensures that previously created blur regions remain visible while editing.

Displaying Blur Boxes

Render every stored region with a dashed outline.

function drawBlurArea(
    area
) {

    overlayContext
        .setLineDash([6, 4]);

    overlayContext
        .strokeStyle =
        "#4f6cff";

    overlayContext
        .strokeRect(

            area.x,

            area.y,

            area.width,

            area.height

        );

}

The outline acts as a guide and doesn't become part of the final PDF.

Blur Options

Users can choose how the blur should be applied.

The tool supports two modes:

Blur selected areas
Blur entire page(s)

The selected option controls the editing behavior.

const blurMode =
document.querySelector(

    'input[name="blurMode"]:checked'

).value;

If Blur selected areas is chosen, users draw blur rectangles manually.

If Blur entire page(s) is selected, the application skips manual selection and prepares to blur the entire page during final processing.

Adjusting Blur Intensity

Different documents require different levels of blur.

A slider lets users control the blur strength before applying the effect.

const blurSlider =
document.getElementById(
    "blurIntensity"
);

let blurIntensity = 6;

blurSlider
.addEventListener(
    "input",
    event => {

        blurIntensity =
        Number(
            event.target.value
        );

    }
);

The selected value is stored with every newly created blur region.

blurArea.intensity =
blurIntensity;

Higher values produce a stronger blur effect.

Managing Multiple Blur Areas

Many documents contain several pieces of confidential information.

Instead of limiting users to a single blur rectangle, the application displays every saved region.

For example:

Blur Area #1

Blur Area #2

Blur Area #3

Each entry includes a remove button.

function removeBlurArea(
    index
) {

    blurAreas.splice(
        index,
        1
    );

    redrawBlurAreas();

    updateBlurList();

}

This allows users to delete only the blur region they no longer need.

To remove all blur regions from the current page:

function clearCurrentPage() {

    const remaining =

    blurAreas.filter(

        area =>

            area.page !==
            currentPage

    );

    blurAreas.length = 0;

    blurAreas.push(
        ...remaining
    );

    redrawBlurAreas();

}

Applying Blur to Pages

Users may want to blur only one page or several pages within a document.

The editor provides three options:

Current page only
All pages
Specific pages

const pageOption =
document.querySelector(

'input[name="pageOption"]:checked'

).value;

If the user selects Specific pages, they can enter values such as:

1, 3-5, 8

These values will later be converted into an array of page numbers before the final PDF is generated.

Applying the Blur Effect

So far, users have uploaded a PDF, selected one or more blur regions, adjusted the blur intensity, and chosen which pages should be processed.

The final step is converting those blur regions into actual blurred content inside the generated PDF.

Rather than modifying the original document directly, the application creates a new PDF while preserving the original file.

Loading the Original PDF

Start by loading the uploaded PDF into PDF-lib.

async function applyBlur() {

    const pdfDoc =

        await PDFLib.PDFDocument.load(
            originalPdfBytes.slice()
        );

    const pages =
        pdfDoc.getPages();

}

Using a copy of the original bytes ensures that the uploaded document remains unchanged.

Processing the Selected Pages

Determine which pages should receive the blur effect.

const selectedPages =

parsePageSelection(

    pageSelection,

    pdfDoc.getPageCount()

);

For example:

Current Page

↓

[2]


All Pages

↓

[1,2,3,4]


Specific Pages

↓

[1,3,5]

Only these pages will be modified during processing.

Rendering Each Page as an Image

Since blur is a pixel-based effect, each selected PDF page is rendered into an off-screen canvas.

const page =

await pdfDocument.getPage(
    pageNumber
);

const viewport =
page.getViewport({

    scale: 2

});

const canvas =
document.createElement(
    "canvas"
);

canvas.width =
viewport.width;

canvas.height =
viewport.height;

Render the page.

await page.render({

    canvasContext:
    canvas.getContext("2d"),

    viewport

}).promise;

The canvas now contains a bitmap version of the PDF page that can be edited.

Applying Blur to Selected Regions

Retrieve all blur regions that belong to the current page.

const pageRegions =

blurAreas.filter(

    area =>

        area.page === pageNumber

);

Loop through every blur region.

pageRegions.forEach(

    area => {

        blurCanvasRegion(

            canvas,

            area

        );

    }

);

Each region is blurred independently.

Blurring the Canvas Region

The browser's Canvas API allows filters to be applied while drawing.

Set the blur filter based on the selected intensity.

context.filter =

`blur(${area.intensity}px)`;

Redraw only the selected region.

context.drawImage(

    canvas,

    area.x,

    area.y,

    area.width,

    area.height,

    area.x,

    area.y,

    area.width,

    area.height

);

After drawing, reset the filter.

context.filter = "none";

Only the selected rectangle becomes blurred while the rest of the page remains unchanged.

Blurring an Entire Page

If the user chooses Blur entire page(s), the process is much simpler.

Apply the filter to the full canvas.

context.filter =

`blur(${blurIntensity}px)`;

context.drawImage(

    canvas,

    0,

    0

);

context.filter =
"none";

The entire rendered page receives the selected blur effect.

Converting the Canvas Back into a PDF Image

After editing the canvas, convert it into an image.

const imageData =

canvas.toDataURL(
    "image/png"
);

Convert the image into bytes.

const bytes =

await fetch(imageData)

.then(

response =>

response.arrayBuffer()

);

Embed the image inside PDF-lib.

const image =

await pdfDoc.embedPng(
    bytes
);

Replace the page contents.

const pdfPage =

pages[
pageNumber - 1
];

const size =
pdfPage.getSize();

pdfPage.drawImage(

    image,

    {

        x: 0,

        y: 0,

        width:
        size.width,

        height:
        size.height

    }

);

Repeat the same process for every selected page.

Showing the Processing State

Generating large PDF files may take a few seconds.

Display a loading state while processing.

applyButton.disabled =
true;

applyButton.textContent =
"Applying...";

After processing finishes:

applyButton.disabled =
false;

applyButton.textContent =
"Apply & Finalize";

This gives users clear feedback that the application is working.

During processing:

Generating the Final PDF

After every page has been processed, save the completed document.

const pdfBytes =

await pdfDoc.save();

const outputBlob =
new Blob(

[pdfBytes],

{

type:
"application/pdf"

}

);

Store the result so it can be previewed and downloaded later.

generatedPdfBlob =
outputBlob;

At this point, the blurred PDF has been successfully generated.

Previewing the Result

Hide the editing interface and display the completed document.

editorSection.hidden =
true;

resultSection.hidden =
false;

The result screen displays:

Final PDF preview
Editable filename
Total pages
File size
Download button

The user can review the processed document before downloading it.

Renaming and Downloading

Before downloading, users may want to rename the generated file.

Create a filename field.

Validate the filename.

function getFilename() {

    let filename =
    outputFilename.value.trim();

    if (!filename) {

        filename =
        "blurred-document.pdf";

    }

    if (
        !filename
        .toLowerCase()
        .endsWith(".pdf")
    ) {

        filename += ".pdf";

    }

    return filename;

}

Display additional file information.

pageCount.textContent =

`Pages:
${finalPdfDocument.numPages}`;

fileSize.textContent =

formatFileSize(
generatedPdfBlob.size
);

Download the processed document.

downloadButton
.addEventListener(

"click",

() => {

    const url =

    URL.createObjectURL(
        generatedPdfBlob
    );

    const link =
    document.createElement(
        "a"
    );

    link.href = url;

    link.download =
    getFilename();

    link.click();

    URL.revokeObjectURL(
        url
    );

});

The browser downloads the completed PDF without sending any files to a remote server.

Demo: How the PDF Blur Tool Works

Let's walk through the complete workflow.

Step 1: Upload the PDF

Users upload a PDF using drag-and-drop or the Select PDF button.

The browser validates the file and prepares it for rendering.

Step 2: Preview the Document

The uploaded PDF appears inside the preview window.

Users can move through the document using the page navigation controls.

Step 3: Configure Blur Settings

Users choose whether to blur selected areas or entire pages.

They can also configure the blur intensity before creating any blur regions.

Step 4: Draw Blur Areas

Users click and drag directly on the PDF preview to create blur rectangles over sensitive content.

Multiple blur regions can be created on the same page.

Step 5: Adjust Blur Intensity

The blur intensity slider controls how strong the blur effect should appear.

Higher values produce a stronger blur.

Step 6: Manage Blur Regions

Individual blur areas can be removed, or all blur regions on the current page can be cleared.

This makes editing much easier before generating the final PDF.

Step 7: Choose the Pages

Users decide whether the blur should be applied to:

Current page
All pages
Specific pages

For example:

1,3-5,8

Step 8: Apply the Blur

After reviewing the settings, users click Apply & Finalize.

The application generates a new PDF containing the selected blur effects.

Step 9: Review the Final Document

The completed PDF appears in the preview window.

Users can verify every blurred region before downloading.

Step 10: Rename and Download

Finally, users rename the output file if needed and click Download.

The browser saves the completed PDF locally.

Performance Tips

Large PDF files can take longer to render and process, but a few simple optimizations can keep the editor responsive.

Render only the page the user is currently viewing instead of loading the entire document.

await renderPage(
    currentPage
);

Reuse the same canvas and redraw only the blur regions when changes are made.

overlayContext.clearRect(
    0,
    0,
    overlayCanvas.width,
    overlayCanvas.height
);

redrawBlurAreas();

During final processing, generate only the pages selected by the user.

for (const page of selectedPages) {

    await processPage(page);

}

Finally, release temporary resources after the download completes.

URL.revokeObjectURL(
    downloadUrl
);

These optimizations reduce memory usage and help the PDF Blur Tool perform smoothly, even with large multi-page documents.

Common Mistakes

One common issue is storing blur coordinates before accounting for the current zoom level.

Always convert preview coordinates into the PDF's coordinate system before generating the final document.

const scaleX =

pdfWidth /
canvas.width;

const scaleY =

pdfHeight /
canvas.height;

Another mistake is allowing blur regions to extend beyond the page boundaries.

Clamp the values before processing.

blurArea.x = Math.max(
0,
blurArea.x
);

blurArea.y = Math.max(
0,
blurArea.y
);

Users should also verify the final preview before downloading, especially when multiple blur regions exist across different pages.

Finally, remember that this project applies a visual blur effect to the rendered PDF pages. If your application requires permanent removal of sensitive content rather than visual obscuring, additional document-redaction techniques are needed.

Conclusion

In this tutorial, you built a browser-based PDF Blur Tool using JavaScript.

You learned how to upload and preview PDF documents, navigate between pages, create and manage multiple blur regions, adjust blur intensity, apply blur to selected pages, generate a new PDF with PDF-lib, preview the processed document, and download the final file – all without uploading data to a server.

By combining PDF.js, the HTML Canvas API, and PDF-lib, you created a privacy-focused PDF editing tool that runs entirely inside the browser.

You can explore the complete workflow using the PDF Blur Tool.

From here, you could extend the project with features such as movable and resizable blur regions, undo and redo support, reusable blur presets, keyboard shortcuts, touch-device editing, or additional annotation tools for even more advanced browser-based PDF editing.

How to Run an AI Extractability Audit on Your Site (I Found 6 Heading Tags That Cost Me Citations)

Chudi Nnorukam — Wed, 22 Jul 2026 23:16:07 +0000

When an AI assistant answers a question, it lifts sentences from a handful of pages and cites them. Whether your page is liftable is not a mystery or a vibe. It's a set of mechanical properties of your HTML that you can measure, score, and fix.

This tutorial walks through the exact audit I ran on my own site, the six invisible heading tags it caught, the one-commit fix, and the CI gate that keeps the problem from coming back.

Here is the punchline up front: my homepage scored 65 out of 100 on extractability. The cause was five UI card components that rendered their titles as

and
tags. Demoting those six headings to ARIA-preserving paragraphs, without changing a single visible pixel or removing one word of content, took the page to 100.

Over the last 90 days, Microsoft's Bing Webmaster Tools reports 1,600 AI citations across 33 of my pages. Extraction is the stage of that pipeline this tutorial teaches you to audit.

Table of Contents

What an Extractability Audit Actually Tests

Prerequisites

Step 1: Pick the Pages Worth Auditing

Step 2: Run the Five Checks

Step 3: Read Your Failure Classes

Step 4: Find the Components Emitting Fake Headings

Step 5: Demote the Headings Without Breaking Accessibility

Step 6: Gate the Fix in CI

What Actually Moved

What I Rejected, and Why

FAQ

What You Accomplished

What an Extractability Audit Actually Tests

A citation from an AI engine is the last step of a three-stage machine pipeline, and your page has to pass every stage:

Retrieve: the engine's crawler is allowed to fetch your page, and does.
Extract: the model finds a clean, self-contained answer in your markup.
Attribute: the engine is confident enough about who said it to put your name next to it.

Most AI-visibility advice concentrates on stage 1 (robots.txt, sitemaps, llms.txt) and stage 3 (schema, entity signals). Stage 2 is where I've found the cheapest wins, because it's pure HTML engineering, and because it fails silently: a page that retrieves fine and attributes fine but extracts poorly simply never appears in answers, and nothing tells you why.

Extractability is the measurable version of stage 2: can a parser walking your rendered HTML find self-contained answer blocks under clearly scoped headings? The audit in this tutorial scores that on a 0 to 100 scale using five checks, each of which you can verify by hand:

Check	What it tests	Weight
F1	The first sentence under every H2 stands alone as an answer	30
F2	The first 200 tokens of the page contain a direct answer	20
F3	Each H2 section opens with an answer in the 40 to 60 word band	20
F4	Share of H2/H3 headings phrased as questions a user would type	20
F5	An FAQ section exists at the article footer	10

A score of 75 or above lands in the EXTRACTABLE band. 40 to 74 is PARTIALLY-EXTRACTABLE. Below 40 is NOT-EXTRACTABLE. The bands come from the AI Visibility Readiness framework I maintain, but the five checks themselves are engine-agnostic: they encode how retrieval-augmented systems chunk pages by heading, embed the chunks, and lift the opening sentences of whichever chunk matches the query.

The critical detail for this tutorial: the audit counts every

,
, and
in your rendered DOM. Not the headings you wrote in your CMS. The headings your component library emits. That gap is where my six invisible failures lived.

Prerequisites

A live website you can measure and deploy (Any stack. My examples are SvelteKit, and every fix translates to React, Vue, or plain HTML.)

Python 3.10+ with `requests` and `beautifulsoup4` (`pip install requests beautifulsoup4`)

Access to your search console data (Google Search Console or Bing Webmaster Tools) to pick pages

A CI system (the example uses GitHub Actions)

About 90 minutes: 20 for the audit, 40 for the fix, 30 for the CI gate

Step 1: Pick the Pages Worth Auditing

Don't audit your whole sitemap. Audit the pages that already have distribution, because extraction fixes multiply whatever retrieval you already earn.

Open Google Search Console, go to Performance, sort pages by impressions over the last 28 days, and look at where your distribution actually lives.

Here's the top of my own report from that export (July 21):

Page Impressions (28d) Clicks Avg position

/blog/claude-fable-5-vs-opus-4-8 17,315 462 6.2

/blog/how-i-built-polymarket-trading-bot 13,649 104 7.6

/blog/claude-code-production-trading-bot 6,540 94 8.5

/blog/aeo-answer-engine-optimization-explained 4,189 1 8.2

Individual posts dominate the impressions, but notice what every one of those posts has in common: they're all rendered by the same layout and card components.

Fixing a component fixes every page that uses it at once, which is why I scoped the audit to the top 3 to 5 content-index pages instead of individual posts: the homepage, your blog index, your topic or category hubs.

Index pages are assembled almost entirely from repeating cards, so they show component damage in its most concentrated form, and any fix propagates to everything else.

I chose these three:

`chudi.dev/` (the homepage)

`chudi.dev/blog` (the writing index)

`chudi.dev/topics` (the topic hub)

Artifact check: you should now have a written list of 3 to 5 URLs. That list is the audit's scope.

Page	Impressions (28d)	Clicks	Avg position
/blog/claude-fable-5-vs-opus-4-8	17,315	462	6.2
/blog/how-i-built-polymarket-trading-bot	13,649	104	7.6
/blog/claude-code-production-trading-bot	6,540	94	8.5
/blog/aeo-answer-engine-optimization-explained	4,189	1	8.2

Step 2: Run the Five Checks

You can score the five checks with about 60 lines of Python. This is a deliberately minimal version of the auditor I run in production. It implements the two checks that catch component damage (F3 and F4) plus a full heading census, which is enough to find the class of bug this tutorial fixes.

import re
import sys
import requests
from bs4 import BeautifulSoup

QUESTION = re.compile(
    r"^\s*(what|how|why|when|where|who|which|is|are|can|do|does|should|will|did)\b|\?\s*$",
    re.IGNORECASE,
)

def audit(url):
    html = requests.get(url, timeout=8, headers={"User-Agent": "extract-audit/1.0"}).text
    soup = BeautifulSoup(html, "html.parser")

    headings = [(h.name, " ".join(h.get_text().split())) for h in soup.find_all(["h1", "h2", "h3"])]
    subheads = [(n, t) for n, t in headings if n in ("h2", "h3")]

    question_rate = (
        sum(1 for _, t in subheads if QUESTION.search(t)) / len(subheads) if subheads else 0.0
    )

    in_band = 0
    h2s = soup.find_all("h2")
    for h2 in h2s:
        first_p = h2.find_next("p")
        words = len(first_p.get_text().split()) if first_p else 0
        if 40 <= words <= 60:
            in_band += 1

    print(f"URL: {url}")
    print(f"Heading census ({len(headings)} total):")
    for name, text in headings:
        print(f"  <{name}> {text[:70]}")
    print(f"F4 question-format rate: {question_rate:.1%} (target >= 50%)")
    print(f"F3 sections opening in the 40-60 word band: {in_band}/{len(h2s)}")

if __name__ == "__main__":
    audit(sys.argv[1])

Run it against each page on your list:

python3 extract_audit.py https://yoursite.com/

The heading census is the part to stare at. It prints every H1/H2/H3 a parser sees, in order, which is frequently not the outline you think you published.

If you want the full five-check scored version with the weighted 0 to 100 composite, the automated audit on citability.dev runs all five checks plus retrieval and attribution layers. The manual version above is enough to complete this tutorial.

Artifact check: a terminal output per page showing the heading census, the F4 rate, and the F3 band count. Screenshot it. It is your before-state.

Step 3: Read Your Failure Classes

Here's what the audit said about my homepage before the fix, pulled from the commit record of the remediation (2026-05-23):

Score: 65/100, PARTIALLY-EXTRACTABLE, ten points under the threshold
F4 question-format rate: 26.7%, far below the 50% pass line
Cause: more than ten headings in the census that I never wrote as headings

The census made the cause obvious. Alongside the section headings I had deliberately tuned ("How do I see it run live?", "What is the retrieval header?") sat a pile of statements like blog post titles and project names, each wrapped in

. I hadn't typed a single one of them into a heading field. My card components had.

This is the general lesson, and it is worth stating as a rule:

The denominator is the design problem. Every heading your components emit joins the denominator of every ratio check an extraction parser runs. Ten card titles as H3s means your carefully tuned question headings are outvoted 10 to 4 by markup you never see.

Failure classes map to fixes like this:

Symptom in the census Failure class Fix (Step)

Headings you never wrote, repeated in card-sized clusters Component-emitted headings Steps 4 and 5

Your own H2s are statements, not questions Authored heading style Rephrase to question form

Sections open with a 15-word teaser or a 120-word ramble Answer-band miss Densify openers to 40 to 60 words

No FAQ block Missing F5 surface Add one at the footer

I had all four classes across my three pages. The component class was the biggest single scorer, and it's the one nobody catches by reading their CMS, so it gets the deep treatment here. (For the record, the authored fixes on my other pages were exactly what the table says: two H2s on my framework page rephrased into question form, and a topic-hub opener expanded from 37 words to roughly 50 to enter the answer band.)

Artifact check: your census annotated with the four failure classes. Count how many headings you didn't author.

Symptom in the census	Failure class	Fix (Step)
Headings you never wrote, repeated in card-sized clusters	Component-emitted headings	Steps 4 and 5
Your own H2s are statements, not questions	Authored heading style	Rephrase to question form
Sections open with a 15-word teaser or a 120-word ramble	Answer-band miss	Densify openers to 40 to 60 words
No FAQ block	Missing F5 surface	Add one at the footer

Step 4: Find the Components Emitting Fake Headings

The census tells you fake headings exist. Your component library tells you where they come from. Grep for heading tags inside your component directory, not your content:

grep -rn "


(React: grep -rn ". Vue: same idea with .vue.)

On my site, this surfaced six heading sites across five components:



Component
Emitted
Instances



BlogCard.svelte
 post title
2


BlogCardFeatured.svelte
 post title
1


ProductCard.svelte
 product name
1


ProjectCard.svelte
 project name
1


JourneyCard.svelte
 milestone title
1


Six tags doesn't sound like much until you remember that cards repeat. One blog index rendering ten BlogCard instances injects ten 
 statements into that page's census. Every card-built page on the site inherits the same dilution, which is exactly why my content-index pages scored worst.
Why do component libraries do this? Because a card title looks like a heading, and because accessibility guidance rightly encourages semantic HTML.
The mistake is subtler: a card title is a link label into another document, not a section heading of this document. The page's real outline is "here are my featured posts", not the title of each post teased below it. HTML has no tag for "title of a different page", so components default to H2/H3, and every parser that walks the page inherits a false outline.
Artifact check: a table like the one above: component, tag emitted, instance count. This is your fix list.
Step 5: Demote the Headings Without Breaking Accessibility
The obvious fix, swapping 
 for a styled  or , has a real cost: screen reader users navigate by heading structure, and card titles are genuinely useful landmarks when scanning a list of posts. Deleting the semantics entirely trades an AI-extraction win for an accessibility loss. That trade isn't necessary.
The fix that preserves both is ARIA heading demotion: replace the literal tag with a paragraph carrying role="heading" and an explicit aria-level.
One important clarification before the diff: the first rule of ARIA is to prefer native HTML elements, and this fix doesn't violate it. The rule applies when the text genuinely is a heading of the current document, and the whole point of Step 4 was establishing that card titles are not. They are link labels into other documents.
Native 
 was the wrong semantics, while the ARIA role is a courtesy that keeps the list-scanning navigation screen reader users already rely on.
Here's the actual diff from my BlogCard.svelte, unchanged except for wrapping:
-
   {post.title}
-
+

What changes and what does not:

Assistive technology sees the same outline. role="heading" plus aria-level="3" is the ARIA-standard equivalent of an 
. Screen readers that navigate by heading still stop here and still announce the level.

Visual styling is untouched. Every class stays on the element. Zero pixels move.

Content is untouched. The fix removes zero words. This matters because most extraction advice tells you to rewrite. But this class of bug needs no rewriting.

HTML-tag parsers stop counting it. Extraction pipelines chunk by literal h1/h2/h3 elements. The card title exits the census, your authored headings get the denominator back, and the ratios you tuned start passing.


Apply the same one-line change at every site on your Step 4 fix list. Mine was one commit touching five components, six occurrences.
Then redeploy and re-run the Step 2 audit. My homepage went from 65 to 100/100 EXTRACTABLE on the post-deploy re-score, with the question-format rate recovering from 26.7% to above the 50% threshold, because the four question headings I had authored were finally the only H2/H3 population on the page.
Artifact check: the after-audit terminal output next to your before screenshot. The heading census should now contain only headings you wrote on purpose.
Step 6: Gate the Fix in CI
Here's the uncomfortable truth about extraction scores: they drift. Content changes, components get added, or a redesign ships a new card.
My homepage, re-audited live while writing this tutorial (July 21), sits at 80: still EXTRACTABLE, but down from its post-fix 100, because a homepage redesign in the intervening weeks changed the section structure again. The blog index and topic hub both still score 100.
That drift is why the durable deliverable of this tutorial isn't the fix. It's the regression gate. Without one, the next well-meaning component ships a new 
 and your score quietly decays. Nothing visible breaks, so nothing gets caught in review.
Mine runs as a GitHub Actions workflow triggered by every successful production deployment, and hard-fails if any audited URL drops out of the EXTRACTABLE band:
name: Post-Deploy Extractability Audit

on:
  deployment_status:

jobs:
  audit:
    if: |
      github.event.deployment_status.state == 'success' &&
      github.event.deployment.environment == 'Production'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install requests beautifulsoup4
      - name: Audit extractability on the live URLs
        run: |
          for url in "https://yoursite.com/" "https://yoursite.com/blog"; do
            python3 scripts/extract_audit.py "$url" --min-score 75 || exit 1
          done

To make the minimal auditor CI-ready, add a --min-score flag that exits nonzero below the threshold. That's a five-line change to the Step 2 script (compute the weighted score from the checks you implement, compare, sys.exit(1)).
The production version of my gate audits five URLs and stacks Lighthouse accessibility thresholds into the same workflow, so the ARIA-demotion contract from Step 5 is enforced from both directions: extraction can't regress below 75, and accessibility can't regress below 95. That pairing is the whole point. The two constraints keep each other honest.
Artifact check: a CI run in your Actions tab that fails when you feed it --min-score 101 (proving it can fail) and passes at 75.
What Actually Moved


The scoreboard for my three pages, all numbers from the same instrument:



Page
Before fix (May)
After fix
Live re-audit (July 21)



Homepage
65 PARTIALLY-EXTRACTABLE
100 EXTRACTABLE
80 EXTRACTABLE


Blog index
below threshold
100 EXTRACTABLE
100 EXTRACTABLE


Topic hub
below threshold
100 EXTRACTABLE
100 EXTRACTABLE




And the downstream metric the audit exists to serve: Bing Webmaster Tools' AI Performance report (the only first-party AI citation dashboard that currently exists. You'll find it in your BWT property under Search Performance) shows my site earning 1,600 AI citations across 33 pages in the 90 days ending July 19, from Microsoft Copilot and partner assistants. That number was 671 in late April, around when this remediation arc started, and roughly 1,500 by late June.
A note on causality, because this is where AI-visibility content usually oversells: the citation growth is correlated with the extraction work, not cleanly attributed to it. Over the same window, I also shipped content, fixed retrieval issues, and grew regular search traffic.
What I can defend: the audit scores are fully causal (the same instrument, before and after, moved because of one commit), the mechanism is documented engine behavior (heading-based chunking), and the citations kept compounding after the fix. What I can't give you is a controlled experiment isolating six heading tags. Nobody really can.
What I Rejected, and Why
Selection bias is the failure mode of tutorials like this one, so here's what I considered and didn't do:

Rewriting the page copy: This is standard extraction advice. But I rejected it because the census showed a structural problem, not a prose problem. My authored sections already passed. Rewriting would have burned days and muddied the measurement.

Plain /
 demotion without ARIA: Two fewer attributes per element. I rejected this because it deletes real navigation structure for screen reader users. The audit wouldn't have noticed the difference, but people would've.

Stuffing FAQ schema on every page: F5 is worth 10 points and JSON-LD is cheap. I rejected this as the first move because it treats the symptom with metadata while leaving the false outline in place. Schema asserts what your page means but the DOM is what gets chunked. Fix the DOM first.

Auditing every page on the sitemap: Completeness is seductive. I rejected this because extraction fixes multiply retrieval, and most pages have little retrieval to multiply. Three index pages covered the highest-impression surfaces and every card component in one pass.

Chasing a 100 score as a standing target: After watching my homepage drift from 100 to 80 through an unrelated redesign while staying comfortably in the EXTRACTABLE band, I set the CI gate at the 75 threshold, not at 100. Gating at perfection turns every content experiment into a CI failure and teaches your team to ignore the gate.


FAQ
Does demoting headings hurt my regular SEO?
The headings that matter for search are the ones describing your document's own structure, and those stay untouched. What you're removing is markup that claimed other documents' titles as your outline.
My organic search impressions grew over the months following the fix. Nothing in Google's guidance requires card titles to be heading elements.
Is this just gaming one audit script?
The five checks encode how retrieval-augmented systems actually process pages: chunk by heading, embed chunks, and lift opening sentences of matching chunks. A false outline degrades that pipeline no matter whose script measures it. You're not optimizing for my auditor. Instead, you're fixing the DOM that every parser sees. The score is a proxy, which is exactly why Step 6 gates the band, not the number.
I use React or Vue, not Svelte. Does anything change?
Nothing structural. The bug lives in JSX and SFC templates identically (
{title}
 inside a Card.tsx), the grep in Step 4 finds it, and role="heading" with aria-level works in every framework because it's plain HTML.
What about the headings inside my actual articles?
Leave them as real 
/ elements. Article body headings are your document's structure and they're precisely what should be in the census. The demotion pattern applies only to components that surface other pages' titles: cards, teasers, related-post widgets, and navigation panels.
How often should I re-audit?
Continuously, which is what Step 6 buys you: the CI gate re-audits on every production deployment, so you never re-audit by hand again.
If you skip the gate, run the Step 2 script monthly and after any change to layout components, navigation, or templates. Content edits inside a page rarely move the score much. Component and template changes are what reshape the census, and those are exactly the changes nobody thinks to re-measure. My own 100 to 80 homepage drift came from a redesign, not from writing.
My score is low but I have no card components. Now what?
Then your failure class is authored, not structural: statement headings (rephrase into questions users type), openers outside the 40 to 60 word band (densify), or a missing FAQ block (add one). The census from Step 2 tells you which. The fixes are writing work rather than component work.
What You Accomplished
You measured a property of your site most owners have never seen: the heading census your components actually emit, and the extractability score it produces.
You traced low scores to the specific components responsible, applied a demotion pattern that satisfies extraction parsers and screen readers simultaneously, and wired a CI gate so the score can never silently regress again.
The wider context, from the first two guides in this series: measuring your AI citation rate across engines tells you whether you're being cited, and shipping an agent-facing surface with WebMCP prepares your site for agents that act rather than read.
This tutorial closes the loop in the middle: making the content you already have liftable. Retrieval determines whether engines see you, attribution determines whether they name you, and extraction, the stage you just audited, determines whether there's anything clean enough to quote.
Run the census on your top three pages this week. If your components are voting in your outline, you now know how to take the vote back.
Thanks for reading!
I'm Chudi Nnorukam, and I keep the longer version of this method, plus the tool that automates the mechanical half of it, at chudi.dev. Check out this page: https://chudi.dev/tools/aeo-audit.

Component	Emitted	Instances
`BlogCard.svelte`	post title	2
`BlogCardFeatured.svelte`	post title	1
`ProductCard.svelte`	product name	1
`ProjectCard.svelte`	project name	1
`JourneyCard.svelte`	milestone title	1

Page	Before fix (May)	After fix	Live re-audit (July 21)
Homepage	65 PARTIALLY-EXTRACTABLE	100 EXTRACTABLE	80 EXTRACTABLE
Blog index	below threshold	100 EXTRACTABLE	100 EXTRACTABLE
Topic hub	below threshold	100 EXTRACTABLE	100 EXTRACTABLE



 How to Build a Reusable Date-Time Picker in React with shadcn/ui 
Vaibhav Gupta — Wed, 22 Jul 2026 16:47:40 +0000
 A date and time picker is one of those components that looks small in a design file and turns into a real time sink once you start building it. You need a calendar, a time selector, a state that keeps both in sync, and usually a range mode and a translated version somewhere down the line, too.
This guide walks through ready-made picker patterns you can drop into a React project today: a combined date and time picker, a date range picker, and a time picker.
Every one of these is available as a Shadcn Date Picker component you can install with a single CLI command instead of building from scratch.
These components are built on both Radix and Base UI primitives, and the versions below use Base UI. They also support copy-prompt functionality, so you can paste them straight into v0, Lovable, or Bolt if that's part of your workflow.
Table of Contents

Prerequisites

What You'll Build

How to Install a Shadcn Date Time Picker

How to Build a Date and Time Picker

How to Build a Date Range Picker

How to Build a Time Picker

Live Preview of the components

Key Concepts Recap

Conclusion

Resources


Prerequisites
To follow along, you should know:

The basics of React, including useState and props

How to install components with the shadcn/ui CLI

Basic Tailwind CSS class names


You also need a React project with shadcn/ui already set up. If you haven't done that yet, run the shadcn/ui CLI setup command in your project before continuing.
What You'll Build

A DateTimePicker component that combines a calendar and time slots into one value.

A TimePicker variant that reuses the same time-slot logic without a calendar.

A DateRangePicker that lets a user pick a start and end date.


How to Install a Shadcn Date Time Picker
All the components below install through the same CLI pattern. Pick the package manager you use:
pnpm
pnpm dlx shadcn@latest add @shadcn-space/date-picker-01

npm
npx shadcn@latest add @shadcn-space/date-picker-01

yarn
yarn dlx shadcn@latest add @shadcn-space/date-picker-01

bun
bunx --bun shadcn@latest add @shadcn-space/date-picker-01

Every other component below installs the same way: just swap the package name at the end of the command. If you haven't set up the CLI in your project yet, this getting-started guide covers that first and shows how to integrate these components when you're working through an MCP-connected editor.
How to Build a Date and Time Picker
This is the combined picker: a calendar popover for the date, plus start and end time fields, wrapped around a booking confirmation flow.
Folder structure:
components
└── shadcn-space
    └── date-picker
        └── date-picker-01.tsx

Component code:
"use client";
import { useState } from "react";
import { format } from "date-fns";
import { CalendarIcon, Clock, ChevronDown, Check } from "lucide-react";
import { cn } from "@/lib/utils";

import { Button } from "@/components/ui/button";
import { Calendar } from "@/components/ui/calendar";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover";

const DateAndTimePickerDemo = () => {
  const [open, setOpen] = useState(false);
  const [date, setDate] = useState(undefined);
  const [bookingStatus, setBookingStatus] = useState<
    "idle" | "loading" | "success"
  >("idle");

  const handleBooking = () => {
    setBookingStatus("loading");
    setTimeout(() => setBookingStatus("success"), 1500);
  };

  return (
    <>
      
        
          
            Select Date
          
          
             setBookingStatus("idle")}
              render={
                
              }
            />
            
               {
                  setDate(d);
                  setOpen(false);
                }}
                className="rounded-md border-none"
              />
            
          
        

        
          
            
               Start Time
            
            
          
          
            
               End Time
            
            
          
        

        
      
    
  );
};

export default DateAndTimePickerDemo;

How This Component Works
This component combines three pieces of state into a simple booking flow:

The selected date

Start and end times

The booking status (idle, loading, success)


The date is stored using React state:
const [date, setDate] = useState(undefined);

When a user selects a day from the calendar, the onSelect callback updates the state and closes the popover:
onSelect={(d) => {
  setDate(d);
  setOpen(false);
}}

The calendar itself lives inside a Popover, which keeps the UI compact. Clicking the trigger button opens the calendar panel:


The displayed date uses date-fns formatting:
format(date, "PPP")

This converts a JavaScript Date object into a readable format such as:
July 22, 2026

The time fields use native HTML inputs:


Native time inputs provide built-in browser support, mobile pickers, keyboard accessibility, and locale-aware formatting without additional libraries.
The booking button demonstrates how UI state can change during an async action:
"idle" → "loading" → "success"

In a real application, handleBooking() would typically call an API endpoint instead of using setTimeout.
This pattern works well for:

Meeting schedulers

Appointment systems

Interview booking tools

Event registration forms

SaaS scheduling workflows


How to Build a Date Range Picker
For anything involving a stay, a rental, or a multi-day booking, you need a range instead of a single date. This component pairs a two-month calendar view with a formatted range label and a computed night count.
Folder structure:
components
└── shadcn-space
    └── date-picker
        └── date-picker-02.tsx

Install this Shadcn Date Range Picker with:
npx shadcn@latest add @shadcn-space/date-picker-02

Component code:
"use client";
import * as React from "react";
import { CalendarIcon, ChevronDown } from "lucide-react";
import { addDays, format } from "date-fns";
import { DateRange } from "react-day-picker";

import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";
import { Calendar } from "@/components/ui/calendar";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover";
import { Label } from "@/components/ui/label";

const DateRangePickerDemo = () => {
  const [date, setDate] = React.useState({
    from: new Date(),
    to: addDays(new Date(), 7),
  });

  return (
    
      
        Select Travel Dates
      
      
        
          
                
                {date?.from ? (
                  date.to ? (
                    <>
                      {format(date.from, "LLL dd, y")} -{" "}
                      {format(date.to, "LLL dd, y")}
                    
                  ) : (
                    format(date.from, "LLL dd, y")
                  )
                ) : (
                  Pick a range
                )}
                
              
            }
          />
          
            
          
        
      
      
        {date?.from && date?.to
          ? `Stay duration: ${Math.round((date.to.getTime() - date.from.getTime()) / (1000 * 60 * 60 * 24))} nights`
          : "Please select a valid date range."}
      
    
  );
};

export default DateRangePickerDemo;

How the Date Range Picker Works
This version switches the Calendar component from single-date mode to range mode:
mode="range"

Instead of storing one Date, the component stores a DateRange object:
{
  from: Date,
  to: Date
}

This makes it easy to work with booking systems, hotel stays, travel forms, and rental applications.
The component displays two calendar months:
numberOfMonths={2}

Showing two months reduces navigation and improves the selection experience for longer stays.
The stay duration is calculated directly from the selected dates:
(date.to.getTime() - date.from.getTime())

This avoids additional libraries and keeps the logic simple.
Compared to the first example:

Uses DateRange instead of a single Date

Uses mode="range"

Displays two months

Adds derived data like total nights


How to Build a Time Picker
Not every form needs a calendar. This one wraps the native in an InputGroup with a clock icon that triggers the browser's own time picker UI on click.
Folder structure:
components
└── shadcn-space
    └── date-picker
        └── date-picker-03.tsx

Install this Shadcn Time Picker with:
npx shadcn@latest add @shadcn-space/date-picker-03

Component code:
"use client";
import { useRef } from "react";
import { Label } from "@/components/ui/label";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@/components/ui/input-group";
import { Clock8Icon } from "lucide-react";

const TimePickerWithIconDemo = () => {
  const inputRef = useRef(null);

  const handleShowPicker = () => {
    if (inputRef.current && "showPicker" in inputRef.current) {
      try {
        inputRef.current.showPicker();
      } catch (error) {
        console.error("Failed to open native picker:", error);
      }
    }
  };

  return (
    
      Select Slot
      
        
          
        
        
      
    
  );
};
export default TimePickerWithIconDemo;

How the Time Picker Works
This component uses the browser's native time picker instead of building a custom dropdown.
The input is referenced with useRef:
const inputRef = useRef(null);

This allows the icon button to access the input element directly.
When users click the clock icon, the browser's picker opens programmatically:
inputRef.current.showPicker();

The showPicker() method is a modern browser API that opens the same interface users would see if they clicked the input manually.
The component wraps the input inside an InputGroup:


This creates a cleaner layout where the icon behaves as part of the field rather than a separate button.
The browser's default picker icon is hidden:
[&::-webkit-calendar-picker-indicator]:hidden

This prevents duplicate icons and gives full control over the UI.
The benefit of this approach is that it keeps:

Native accessibility

Mobile keyboard support

Locale-aware formatting

Better browser compatibility


Instead of rebuilding time selection from scratch, the component improves the native experience with custom styling.
Live Preview of the Components


Key Concepts Recap

Pick the pattern that matches the data you're collecting: A single date and time for bookings, a range for stays, a bare time field for slots.

Every component installs the same way: One CLI command per component: pnpm, npm, yarn, and bun. All are supported. Adding a new picker to a project takes one line, not a manual build.

The date and time picker separates date state from time state, then combines them at the confirmation step. This keeps the calendar and the time inputs from getting out of sync.

The range picker leans on the Calendar's built-in mode="range": The two-month view and the night count come from the selection state, not custom range math.

The time picker wraps the native  instead of replacing it: This keeps native accessibility and mobile keyboard behavior intact.


Conclusion
You now have working picker patterns for React: a date and time picker for bookings, a date range picker for stays, and a plain time picker for slots.
Each one installs with a single CLI command, so you can pick whichever one matches the form you're building and have it running in minutes.
Resources

shadcn/ui documentation: For the official Popover, Calendar, and Button component APIs

date-fns documentation: For the date helper functions and locale files used in this tutorial

react-day-picker documentation: For the range and multi-date selection modes that power the shadcn/ui Calendar

MDN: ARIA live regions: For more on how role="alert" works

Shadcn Date Time Picker components: If you want more prebuilt date and time picker variants to compare against.

Full Shadcn components library: For other shadcn/ui-compatible components

Guide to free Shadcn date and time pickers


 


 How to Build a Browser-Based PDF Signature Tool Using JavaScript 
Bhavin Sheth — Mon, 20 Jul 2026 20:47:13 +0000
 PDF documents are commonly used for agreements, forms, approvals, invoices, reports, applications, and other documents that may need a signature or additional text before they are shared.
A traditional workflow often involves printing the document, signing it by hand, scanning it again, and sending the new file. For a simple electronic signature, that process adds unnecessary steps.
In this tutorial, you'll build a browser-based PDF Signature Tool using JavaScript. Users will be able to upload a PDF, preview and navigate its pages, and add content directly to the document.
The application will support two main element types: Signature and Text/Stamp.
For signatures, users can draw directly in the browser, type their name and choose a signature style, or upload an existing signature image. For text-based elements, they can enter custom text or use preset stamps such as APPROVED, CONFIDENTIAL, DRAFT, and PAID.
After creating an element, users can position it on the PDF preview and adjust properties such as scale, rotation, opacity, font size, and color. The element can then be applied to the current page, every page, or a specific set of pages.
Once processing is complete, the application generates a new PDF for review. Users can preview the result, rename the output file, check its page count and file size, and download it directly from the browser.
The project uses PDF.js for document rendering and PDF-lib for modifying and generating the final PDF.
By the end of this tutorial, you'll understand how to build an interactive PDF editing workflow that combines canvas-based input, image embedding, text placement, coordinate conversion, page selection, and client-side file generation.
What We'll Cover:

What This PDF Signature Tool Can Do

Electronic Signatures vs Digital Signatures

How the Browser-Based Workflow Works

Project Setup

What Libraries Are We Using?

Uploading and Previewing the PDF

Choosing an Element to Add

Creating a Signature

Drawing a Signature

Typing a Signature

Uploading a Signature Image

Adding Text and Preset Stamps

Positioning and Styling the Element

Applying the Element to Selected Pages

Applying and Finalizing the PDF

Generating the Signed PDF

Previewing the Final PDF

Renaming and Downloading the Final PDF

Demo: How the PDF Signature Tool Works

Handling Signature Transparency

Important Notes and Common Mistakes

Conclusion


What This PDF Signature Tool Can Do
The application provides a single editing workflow for adding signatures, text, and common document stamps to PDF pages.
When Signature is selected, users can create the signature in three different ways.

The Draw option provides a canvas where the user can write a signature using a mouse, trackpad, stylus, or touch input.

The Type option converts entered text into a signature-style element. Users can type their name, adjust the size, and choose from the available signature styles.

The Upload option accepts an existing signature image. This is useful for someone who already has a transparent PNG or another supported image of their handwritten signature.


The second element type is Text/Stamp. Users can enter custom text such as:
Signed on: 08-09-2025

They can also quickly choose a predefined stamp:
APPROVED
CONFIDENTIAL
DRAFT
PAID

After an element has been created, the application provides controls for its placement and appearance. Users can move it to the required location and adjust its scale, rotation, opacity, and position.
Text and stamp elements can additionally use configurable font sizes and colors.
The page controls determine where the selected element will be applied. A signature may belong only on the final page of a contract, while a CONFIDENTIAL stamp may need to appear on every page.
The application therefore supports:
Current page only
All pages
Specific pages

The goal is to provide one consistent workflow for several common PDF editing tasks without requiring separate tools for each element type.
Electronic Signatures vs Digital Signatures
Before building the application, it's important to distinguish between an electronic signature and a digital signature.
The tool in this tutorial creates an electronic signature workflow.
A drawn signature, typed signature, or uploaded signature image is placed visually onto the PDF page. This is similar to signing a document by hand and inserting a visible representation of that signature into the file.
For example, a user might draw a signature on a canvas:
const signatureImage =
    signatureCanvas.toDataURL("image/png");

The generated image can then be embedded into the PDF.
A digital signature is technically different.
Certificate-based digital signatures use cryptographic methods to help verify document integrity and the identity associated with a signing certificate. They may involve digital certificates, private keys, signature validation, and trust chains.
Simply placing a handwritten signature image on a PDF doesn't create that type of cryptographic verification.
This distinction matters because the terms are sometimes used interchangeably in everyday conversation even though the underlying technologies are different.
The project we're building focuses on visual electronic signatures and document elements. It doesn't create certificate-based cryptographic digital signatures.
Keeping that distinction clear makes it easier to understand exactly what the application does and what would require a more advanced signing system.
How the Browser-Based Workflow Works
The process begins when a user selects a PDF file.
PDF.js loads the document and renders the current page into a browser canvas. Previous and next buttons allow the user to navigate through the PDF before choosing where to place an element.
The user then selects one of two element types:
Signature
Text/Stamp

If Signature is selected, the application provides three creation methods:
Draw
Type
Upload

The selected signature is converted into an element that can be displayed over the PDF preview.
If Text/Stamp is selected, the application instead creates a text element using either custom content or one of the predefined stamp values.
The complete workflow looks like this:
Upload PDF
    ↓
Render and Navigate Pages
    ↓
Choose Signature or Text/Stamp
    ↓
Create the Element
    ↓
Position and Style It
    ↓
Choose Target Pages
    ↓
Apply & Finalize
    ↓
Generate the New PDF
    ↓
Preview the Result
    ↓
Rename and Download

During editing, the element displayed over the PDF preview is only a browser-side representation. Its position must later be translated into coordinates that match the actual PDF page.
For example, the application may store an element like this:
const element = {
    type: "signature",
    x: 622,
    y: 496,
    scale: 1.14,
    rotation: 0,
    opacity: 1
};

When the user clicks Apply & Finalize, those values are used to calculate the final placement inside the PDF.
This separation between the interactive preview and the final PDF generation is the foundation of the project. It allows users to visually prepare the document first and create the modified PDF only after the placement is ready.
Project Setup
To keep the project easy to understand, we'll use three main files:
pdf-signature-tool/
│
├── index.html
├── style.css
└── script.js

The HTML file contains the upload interface, PDF preview, editing controls, final preview, and download section.
The CSS file handles the layout and visual states.
The JavaScript file manages PDF loading, page rendering, signature creation, text and stamp elements, positioning, final PDF generation, and downloading.
Start with the basic HTML structure:




    

    

    PDF Signature Tool

    





    

        

            PDF Signature Tool

            
                Upload your PDF to add your
                electronic signature.
            

            

                Drag & Drop PDF Here

                Or click to browse file

                

                

            

        

        

            

                

                    

                    

                

                

                    

                    
                        Page 1 of 1
                    

                    

                

            

            

                

            

        

        

            

        

    

    




The previewContainer is especially important.
It contains two layers:
PDF Canvas
    +
Interactive Element Layer

The PDF page is rendered onto the canvas, while signatures, text, and stamps are displayed in a separate overlay.
This allows users to move and style an element without modifying the original PDF every time they make a small adjustment.
The overlay should match the dimensions and position of the PDF canvas.
#previewContainer {
    position: relative;
    display: inline-block;
}

#pdfCanvas {
    display: block;
}

#elementLayer {
    position: absolute;
    inset: 0;
    pointer-events: none;
}

Individual signature and text elements can later enable their own pointer interactions.
.pdf-element {
    position: absolute;
    cursor: move;
    pointer-events: auto;
    transform-origin: center;
}

This layered structure becomes the foundation of the interactive editor.
What Libraries Are We Using?
This project uses two JavaScript libraries for different parts of the PDF workflow.
PDF.js for Rendering and Previewing
PDF.js is responsible for reading the uploaded document and rendering its pages inside the browser.
A page can be loaded like this:
const page =
    await pdfDocument.getPage(
        currentPage
    );

The page is then rendered to a canvas:
const viewport =
    page.getViewport({
        scale: 1.5
    });

const context =
    pdfCanvas.getContext("2d");

pdfCanvas.width =
    viewport.width;

pdfCanvas.height =
    viewport.height;

await page.render({

    canvasContext: context,

    viewport

}).promise;

PDF.js handles the visual preview.
PDF-lib for Modifying the PDF
PDF-lib is used later when the user clicks Apply & Finalize.
It allows us to load the original PDF bytes and add content to its pages.
For example:
const pdfDoc =
    await PDFLib.PDFDocument.load(
        originalPdfBytes
    );

An uploaded PNG signature can then be embedded:
const signatureImage =
    await pdfDoc.embedPng(
        signatureBytes
    );

Text can also be drawn directly onto a PDF page:
page.drawText(
    "APPROVED",
    {
        x: 100,
        y: 100,
        size: 18
    }
);

The two libraries therefore have separate responsibilities:
PDF.js
→ Load and visually render PDF pages

PDF-lib
→ Modify pages and generate the final PDF

Separating these responsibilities keeps the editor easier to manage.
Include both libraries in the project before script.js.






Configure the PDF.js worker as well:
pdfjsLib.GlobalWorkerOptions.workerSrc =
    "https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js";

For a production project, pin and test the exact library versions you use rather than automatically loading an unspecified latest release.
Uploading and Previewing the PDF
The first interactive step is accepting the user's PDF.
Get references to the required elements:
const pdfInput =
    document.getElementById(
        "pdfInput"
    );

const selectPdfButton =
    document.getElementById(
        "selectPdfButton"
    );

const dropZone =
    document.getElementById(
        "dropZone"
    );

const uploadSection =
    document.getElementById(
        "uploadSection"
    );

const editorSection =
    document.getElementById(
        "editorSection"
    );

const pdfCanvas =
    document.getElementById(
        "pdfCanvas"
    );

We also need a few variables to store the current document state.
let pdfDocument = null;

let originalPdfBytes = null;

let currentPage = 1;

let totalPages = 0;

Clicking the custom button opens the hidden file input.
selectPdfButton.addEventListener(
    "click",
    () => {

        pdfInput.click();

    }
);

When a file is selected, pass it to the PDF loading function.
pdfInput.addEventListener(
    "change",
    event => {

        const file =
            event.target.files[0];

        if (file) {

            loadPdf(file);

        }

    }
);

Before processing the file, validate its type.
async function loadPdf(file) {

    if (
        file.type !==
        "application/pdf"
    ) {

        alert(
            "Please select a valid PDF file."
        );

        return;

    }

}

Read the file as an ArrayBuffer.
const arrayBuffer =
    await file.arrayBuffer();

Keep a copy of the original bytes because PDF.js and PDF-lib will use the document at different stages.
originalPdfBytes =
    new Uint8Array(
        arrayBuffer
    );

Now load the document with PDF.js.
pdfDocument =
    await pdfjsLib
        .getDocument({
            data:
                originalPdfBytes.slice()
        })
        .promise;

Store the number of pages.
totalPages =
    pdfDocument.numPages;

currentPage = 1;

Switch from the upload interface to the editor.
uploadSection.hidden = true;

editorSection.hidden = false;

Finally, render the first page.
await renderPage(currentPage);

The complete loading function becomes:
async function loadPdf(file) {

    if (
        file.type !==
        "application/pdf"
    ) {

        alert(
            "Please select a valid PDF file."
        );

        return;

    }

    const arrayBuffer =
        await file.arrayBuffer();

    originalPdfBytes =
        new Uint8Array(
            arrayBuffer
        );

    pdfDocument =
        await pdfjsLib
            .getDocument({
                data:
                    originalPdfBytes.slice()
            })
            .promise;

    totalPages =
        pdfDocument.numPages;

    currentPage = 1;

    uploadSection.hidden = true;

    editorSection.hidden = false;

    await renderPage(currentPage);

}

For drag-and-drop support, prevent the browser's default behavior.
dropZone.addEventListener(
    "dragover",
    event => {

        event.preventDefault();

        dropZone.classList.add(
            "drag-active"
        );

    }
);

Remove the active state when the file leaves the drop area.
dropZone.addEventListener(
    "dragleave",
    () => {

        dropZone.classList.remove(
            "drag-active"
        );

    }
);

Handle the dropped file:
dropZone.addEventListener(
    "drop",
    event => {

        event.preventDefault();

        dropZone.classList.remove(
            "drag-active"
        );

        const file =
            event.dataTransfer.files[0];

        if (file) {

            loadPdf(file);

        }

    }
);



Rendering the Current PDF Page
The renderPage() function loads one page from the PDF and displays it on the canvas.
async function renderPage(
    pageNumber
) {

    const page =
        await pdfDocument.getPage(
            pageNumber
        );

    const viewport =
        page.getViewport({
            scale: 1.5
        });

    const context =
        pdfCanvas.getContext("2d");

    pdfCanvas.width =
        viewport.width;

    pdfCanvas.height =
        viewport.height;

    await page.render({

        canvasContext: context,

        viewport

    }).promise;

    updatePageInfo();

}

Because the interactive element layer sits above the canvas, it must use the same dimensions.
const elementLayer =
    document.getElementById(
        "elementLayer"
    );

elementLayer.style.width =
    `${viewport.width}px`;

elementLayer.style.height =
    `${viewport.height}px`;

Add those lines inside renderPage() after setting the canvas dimensions.
The page information can then be updated:
function updatePageInfo() {

    pageInfo.textContent =
        `Page ${currentPage} of ${totalPages}`;

}

At this point, the uploaded PDF page is visible, but users still need a way to move through multi-page documents.
Adding PDF Page Navigation
Get the navigation controls:
const previousPage =
    document.getElementById(
        "previousPage"
    );

const nextPage =
    document.getElementById(
        "nextPage"
    );

const pageInfo =
    document.getElementById(
        "pageInfo"
    );

The previous button decreases the page number.
previousPage.addEventListener(
    "click",
    async () => {

        if (currentPage <= 1) {
            return;
        }

        currentPage--;

        await renderPage(
            currentPage
        );

    }
);

The next button moves forward.
nextPage.addEventListener(
    "click",
    async () => {

        if (
            currentPage >=
            totalPages
        ) {
            return;
        }

        currentPage++;

        await renderPage(
            currentPage
        );

    }
);

The boundary checks prevent navigation outside the document.
For a 12-page PDF, the interface may display:
Page 12 of 12

The previous button remains available, while the next action can be disabled because the user is already on the final page.
function updateNavigationState() {

    previousPage.disabled =
        currentPage === 1;

    nextPage.disabled =
        currentPage ===
        totalPages;

}

Call this function whenever a new page is rendered.
function updatePageInfo() {

    pageInfo.textContent =
        `Page ${currentPage} of ${totalPages}`;

    updateNavigationState();

}

The user can now upload a PDF, preview its pages, and navigate to the exact page where a signature, custom text, or document stamp needs to be placed.


Choosing an Element to Add
Once the PDF is loaded and the correct page is visible, the user can choose what type of element to place on the document.
The editor provides two options:
Signature
Text/Stamp

Create the element selector:


    1. Choose Element

    
        
        Signature
    

    
        
        Text/Stamp
    



Get the controls in JavaScript:
const elementTypeInputs =
    document.querySelectorAll(
        'input[name="elementType"]'
    );

const signatureControls =
    document.getElementById(
        "signatureControls"
    );

const textControls =
    document.getElementById(
        "textControls"
    );

Listen for changes:
elementTypeInputs.forEach(
    input => {

        input.addEventListener(
            "change",
            event => {

                const type =
                    event.target.value;

                if (
                    type ===
                    "signature"
                ) {

                    signatureControls.hidden =
                        false;

                    textControls.hidden =
                        true;

                } else {

                    signatureControls.hidden =
                        true;

                    textControls.hidden =
                        false;

                }

            }
        );

    }
);

This keeps the interface focused. Signature-specific controls appear only when the user is creating a signature, while text and stamp controls appear when that element type is selected.
Creating a Signature
The signature workflow supports three methods:
Draw
Type
Upload

Create the method selector:


    2. Create Signature

    

        

        

        

    

    

    
    

    
    



Track the currently selected method:
let signatureMethod =
    "draw";

Switch between the three panels:
const signatureTabs =
    document.querySelectorAll(
        ".signature-tabs button"
    );

signatureTabs.forEach(
    button => {

        button.addEventListener(
            "click",
            () => {

                signatureMethod =
                    button.dataset.method;

                showSignatureMethod(
                    signatureMethod
                );

            }
        );

    }
);

The panel switching function can hide the inactive methods:
function showSignatureMethod(
    method
) {

    drawPanel.hidden =
        method !== "draw";

    typePanel.hidden =
        method !== "type";

    uploadPanel.hidden =
        method !== "upload";

}

Each method creates the same type of final element (a signature) but the source of that signature is different.
Drawing a Signature
The Draw option allows users to create a handwritten signature directly in the browser.
Add a canvas to the Draw panel:


    

    



Get the drawing context:
const signatureCanvas =
    document.getElementById(
        "signatureCanvas"
    );

const signatureContext =
    signatureCanvas.getContext(
        "2d"
    );

let isDrawing = false;

Begin drawing when the pointer touches the canvas:
signatureCanvas.addEventListener(
    "pointerdown",
    event => {

        isDrawing = true;

        const rect =
            signatureCanvas
                .getBoundingClientRect();

        signatureContext.beginPath();

        signatureContext.moveTo(

            event.clientX -
                rect.left,

            event.clientY -
                rect.top

        );

    }
);

Continue the line while the pointer moves:
signatureCanvas.addEventListener(
    "pointermove",
    event => {

        if (!isDrawing) {
            return;
        }

        const rect =
            signatureCanvas
                .getBoundingClientRect();

        signatureContext.lineTo(

            event.clientX -
                rect.left,

            event.clientY -
                rect.top

        );

        signatureContext.stroke();

    }
);

Stop drawing when the pointer is released:
signatureCanvas.addEventListener(
    "pointerup",
    () => {

        isDrawing = false;

    }
);

signatureCanvas.addEventListener(
    "pointerleave",
    () => {

        isDrawing = false;

    }
);

Set a few drawing properties:
signatureContext.lineWidth = 2;

signatureContext.lineCap =
    "round";

signatureContext.lineJoin =
    "round";

For touch devices, prevent the browser from interpreting drawing gestures as page scrolling:
#signatureCanvas {
    touch-action: none;
    cursor: crosshair;
}

The Clear button resets the drawing canvas:
clearSignature.addEventListener(
    "click",
    () => {

        signatureContext.clearRect(

            0,
            0,

            signatureCanvas.width,
            signatureCanvas.height

        );

    }
);

Once the signature is ready, convert the canvas into a PNG data URL:
const drawnSignature =
    signatureCanvas.toDataURL(
        "image/png"
    );

Because the canvas can preserve transparency, the resulting signature can be placed over the PDF without adding an unwanted rectangular background.
The generated image can now be displayed inside the interactive element layer.
function useDrawnSignature() {

    const image =
        new Image();

    image.src =
        signatureCanvas.toDataURL(
            "image/png"
        );

    image.onload =
        () => {

            createSignatureElement(
                image.src
            );

        };

}

This gives the user a visual signature element that can later be positioned over the PDF page.
Typing a Signature
Not every user has a touchscreen, stylus, or existing signature image.
The Type option allows users to enter their name and choose a signature-style appearance.
Add the input controls:


    

    
        Font Size
    

    

    
    



Listen for text changes:
typedSignature.addEventListener(
    "input",
    updateTypedSignatures
);

Create several style previews:
const signatureFonts = [

    "cursive",

    "'Brush Script MT', cursive",

    "'Segoe Script', cursive"

];

Render the available options:
function updateTypedSignatures() {

    const value =
        typedSignature.value.trim();

    signatureStyles.innerHTML = "";

    if (!value) {
        return;
    }

    signatureFonts.forEach(
        font => {

            const option =
                document.createElement(
                    "button"
                );

            option.textContent =
                value;

            option.style.fontFamily =
                font;

            option.style.fontSize =
                `${signatureFontSize.value}px`;

            option.addEventListener(
                "click",
                () => {

                    createTypedSignature(
                        value,
                        font
                    );

                }
            );

            signatureStyles.appendChild(
                option
            );

        }
    );

}

A typed signature can be converted to an image using another canvas.
function createTypedSignature(
    text,
    fontFamily
) {

    const canvas =
        document.createElement(
            "canvas"
        );

    const context =
        canvas.getContext("2d");

    const fontSize =
        Number(
            signatureFontSize.value
        );

    context.font =
        `${fontSize}px ${fontFamily}`;

    const width =
        context.measureText(
            text
        ).width;

    canvas.width =
        Math.ceil(width + 40);

    canvas.height =
        Math.ceil(fontSize * 2);

    context.font =
        `${fontSize}px ${fontFamily}`;

    context.textBaseline =
        "middle";

    context.fillText(
        text,
        20,
        canvas.height / 2
    );

    const imageUrl =
        canvas.toDataURL(
            "image/png"
        );

    createSignatureElement(
        imageUrl
    );

}

The typed signature is now treated like the drawn signature: it becomes an image element that can be positioned and later embedded into the PDF.


Uploading a Signature Image
The third option allows users to upload an existing signature image.
Add a file input:


    

    
        No file chosen
    



Listen for file selection:
signatureUpload.addEventListener(
    "change",
    event => {

        const file =
            event.target.files[0];

        if (!file) {
            return;
        }

        loadSignatureImage(file);

    }
);

Validate the image:
function loadSignatureImage(
    file
) {

    const allowedTypes = [

        "image/png",

        "image/jpeg"

    ];

    if (
        !allowedTypes.includes(
            file.type
        )
    ) {

        alert(
            "Please upload a PNG or JPEG image."
        );

        return;

    }

}

Read the selected image:
const reader =
    new FileReader();

reader.onload =
    event => {

        createSignatureElement(
            event.target.result
        );

};

reader.readAsDataURL(file);

Display the selected filename:
selectedSignatureFile.textContent =
    `Selected: ${file.name}`;

The complete function becomes:
function loadSignatureImage(
    file
) {

    const allowedTypes = [

        "image/png",

        "image/jpeg"

    ];

    if (
        !allowedTypes.includes(
            file.type
        )
    ) {

        alert(
            "Please upload a PNG or JPEG image."
        );

        return;

    }

    selectedSignatureFile.textContent =
        `Selected: ${file.name}`;

    const reader =
        new FileReader();

    reader.onload =
        event => {

            createSignatureElement(
                event.target.result
            );

        };

    reader.readAsDataURL(file);

}

A transparent PNG usually works particularly well because only the signature strokes remain visible over the document.


Creating the Signature Preview Element
All three signature methods eventually call the same function:
createSignatureElement(imageUrl);

This means the rest of the editor doesn't need separate positioning logic for drawn, typed, and uploaded signatures.
Create the preview element:
let activeElement = null;

function createSignatureElement(
    imageUrl
) {

    elementLayer.innerHTML = "";

    const image =
        document.createElement(
            "img"
        );

    image.src =
        imageUrl;

    image.className =
        "pdf-element signature-element";

    image.style.left =
        "100px";

    image.style.top =
        "100px";

    image.style.width =
        "180px";

    elementLayer.appendChild(
        image
    );

    activeElement = {

        type: "signature",

        source: imageUrl,

        element: image,

        x: 100,

        y: 100,

        scale: 1,

        rotation: 0,

        opacity: 1

    };

}

The preview now represents the signature that will eventually be written into the PDF.
The same state object can later be updated when the user changes the signature's position, scale, rotation, or opacity.
Adding Text and Preset Stamps
The second main element type is Text/Stamp.
This mode is useful when a document needs a short label, status, date, or other text rather than a handwritten signature.
Create the controls:


    2. Add Text or Stamp

    

    

        

        

        

        

    

    
        Size

        
    

    
        Color

        
    



Custom text can be displayed as the user types:
customText.addEventListener(
    "input",
    () => {

        createTextElement(
            customText.value
        );

    }
);

Preset stamps can update the same text input:
const stampButtons =
    document.querySelectorAll(
        "[data-stamp]"
    );

stampButtons.forEach(
    button => {

        button.addEventListener(
            "click",
            () => {

                const stamp =
                    button.dataset.stamp;

                customText.value =
                    stamp;

                createTextElement(
                    stamp
                );

            }
        );

    }
);

Create the text preview:
function createTextElement(
    text
) {

    if (!text.trim()) {

        elementLayer.innerHTML = "";

        activeElement = null;

        return;

    }

    elementLayer.innerHTML = "";

    const textElement =
        document.createElement(
            "div"
        );

    textElement.className =
        "pdf-element text-element";

    textElement.textContent =
        text;

    textElement.style.left =
        "100px";

    textElement.style.top =
        "100px";

    textElement.style.fontSize =
        `${textSize.value}px`;

    textElement.style.color =
        textColor.value;

    elementLayer.appendChild(
        textElement
    );

    activeElement = {

        type: "text",

        text,

        element:
            textElement,

        x: 100,

        y: 100,

        fontSize:
            Number(
                textSize.value
            ),

        color:
            textColor.value,

        rotation: 0,

        opacity: 1

    };

}

When the size changes, update the current element:
textSize.addEventListener(
    "input",
    () => {

        if (
            activeElement?.type !==
            "text"
        ) {
            return;
        }

        activeElement.fontSize =
            Number(
                textSize.value
            );

        activeElement
            .element
            .style
            .fontSize =
                `${textSize.value}px`;

    }
);

Do the same for the color:
textColor.addEventListener(
    "input",
    () => {

        if (
            activeElement?.type !==
            "text"
        ) {
            return;
        }

        activeElement.color =
            textColor.value;

        activeElement
            .element
            .style
            .color =
                textColor.value;

    }
);

The user can now enter custom content such as:
Signed on: 08-09-2025

or quickly select a predefined document stamp.


At this point, the application can create content using all of the available input methods: a drawn signature, typed signature, uploaded signature image, custom text, or preset document stamp.
Positioning and Styling the Element
After creating a signature, text label, or preset stamp, the next step is positioning it correctly on the PDF page.
The preview element sits inside the elementLayer created earlier. Because this layer matches the PDF canvas dimensions, users can move the element visually before anything is written into the final PDF.
The editor also provides controls for:

Scale

Rotation

Opacity

X position

Y position


The exact controls can vary depending on the active element. For example, scale is particularly useful for signatures, while text size and color are handled by the Text/Stamp controls from the previous section.
Create the placement controls:


    3. Placement & Style

    
        Rotation (°)

        
    

    
        Opacity

        
    

    
        X Position

        
    

    
        Y Position

        
    



For signature elements, add a scale control:

    Scale (100%)

    


Get the controls in JavaScript:
const scaleInput =
    document.getElementById(
        "scaleInput"
    );

const scaleValue =
    document.getElementById(
        "scaleValue"
    );

const rotationInput =
    document.getElementById(
        "rotationInput"
    );

const opacityInput =
    document.getElementById(
        "opacityInput"
    );

const xPosition =
    document.getElementById(
        "xPosition"
    );

const yPosition =
    document.getElementById(
        "yPosition"
    );

We'll use a single function to update the visual transformation.
function updateElementTransform() {

    if (!activeElement) {
        return;
    }

    activeElement.element.style.transform =
        `
            scale(${activeElement.scale})
            rotate(${activeElement.rotation}deg)
        `;

    activeElement.element.style.opacity =
        activeElement.opacity;

}

For text elements, initialize scale as 1 so the same transformation function can still be used.
activeElement = {

    type: "text",

    text,

    element: textElement,

    x: 100,

    y: 100,

    scale: 1,

    rotation: 0,

    opacity: 1

};

Changing the Element Scale
When the user moves the scale slider, convert the percentage into a decimal value.
scaleInput.addEventListener(
    "input",
    () => {

        if (!activeElement) {
            return;
        }

        const percentage =
            Number(
                scaleInput.value
            );

        activeElement.scale =
            percentage / 100;

        scaleValue.textContent =
            `${percentage}%`;

        updateElementTransform();

    }
);

A value of 100% represents the original preview size.
50%  → 0.5
100% → 1
114% → 1.14
200% → 2

This makes it easy to enlarge or reduce an uploaded, drawn, or typed signature without creating a new image.
Rotating the Element
The rotation input stores the angle in degrees.
rotationInput.addEventListener(
    "input",
    () => {

        if (!activeElement) {
            return;
        }

        activeElement.rotation =
            Number(
                rotationInput.value
            );

        updateElementTransform();

    }
);

A rotation of 0 keeps the element horizontal, while positive or negative values rotate it around its center.
Adjusting Opacity
Opacity can be useful for stamps, watermarks, and other document labels.
Convert the percentage slider to a value between 0 and 1.
opacityInput.addEventListener(
    "input",
    () => {

        if (!activeElement) {
            return;
        }

        activeElement.opacity =
            Number(
                opacityInput.value
            ) / 100;

        updateElementTransform();

    }
);

For example:
100% → 1
75%  → 0.75
50%  → 0.5

The same opacity value will later be used when generating the final PDF.
Dragging an Element Across the PDF Preview
Typing X and Y coordinates manually is useful for precise adjustments, but most users will prefer to drag the element directly to the required location.
Track the dragging state:
let isDragging = false;

let dragOffsetX = 0;

let dragOffsetY = 0;

When a signature or text element is created, attach the dragging behavior.
function enableDragging(
    element
) {

    element.addEventListener(
        "pointerdown",
        event => {

            isDragging = true;

            const elementRect =
                element
                    .getBoundingClientRect();

            dragOffsetX =
                event.clientX -
                elementRect.left;

            dragOffsetY =
                event.clientY -
                elementRect.top;

            element.setPointerCapture(
                event.pointerId
            );

        }
    );

}

Call this function when creating an element.
enableDragging(image);

or:
enableDragging(textElement);

Next, listen for pointer movement.
elementLayer.addEventListener(
    "pointermove",
    event => {

        if (
            !isDragging ||
            !activeElement
        ) {
            return;
        }

        const layerRect =
            elementLayer
                .getBoundingClientRect();

        const x =
            event.clientX -
            layerRect.left -
            dragOffsetX;

        const y =
            event.clientY -
            layerRect.top -
            dragOffsetY;

        moveActiveElement(
            x,
            y
        );

    }
);

Create a reusable movement function:
function moveActiveElement(
    x,
    y
) {

    if (!activeElement) {
        return;
    }

    activeElement.x = x;

    activeElement.y = y;

    activeElement.element.style.left =
        `${x}px`;

    activeElement.element.style.top =
        `${y}px`;

    xPosition.value =
        Math.round(x);

    yPosition.value =
        Math.round(y);

}

Stop dragging when the pointer is released.
elementLayer.addEventListener(
    "pointerup",
    () => {

        isDragging = false;

    }
);

elementLayer.addEventListener(
    "pointercancel",
    () => {

        isDragging = false;

    }
);

Now the signature or text element can be moved directly over the document.
For example, an uploaded signature may be positioned near the bottom-right corner of the final page.


Updating the Position Manually
The X and Y fields provide another way to position the element.
Listen for changes to the X coordinate:
xPosition.addEventListener(
    "input",
    () => {

        if (!activeElement) {
            return;
        }

        const x =
            Number(
                xPosition.value
            );

        moveActiveElement(
            x,
            activeElement.y
        );

    }
);

Do the same for Y:
yPosition.addEventListener(
    "input",
    () => {

        if (!activeElement) {
            return;
        }

        const y =
            Number(
                yPosition.value
            );

        moveActiveElement(
            activeElement.x,
            y
        );

    }
);

Dragging and manual coordinate entry remain synchronized. Moving the element updates the fields, while changing the fields moves the preview element.
Keeping the Element Inside the Page
Without boundaries, users could accidentally drag an element completely outside the PDF preview.
We can limit the position before saving it.
function clampPosition(
    x,
    y
) {

    const element =
        activeElement.element;

    const maxX =
        elementLayer.clientWidth -
        element.offsetWidth;

    const maxY =
        elementLayer.clientHeight -
        element.offsetHeight;

    return {

        x:
            Math.max(
                0,
                Math.min(x, maxX)
            ),

        y:
            Math.max(
                0,
                Math.min(y, maxY)
            )

    };

}

Use it inside moveActiveElement():
const position =
    clampPosition(
        x,
        y
    );

activeElement.x =
    position.x;

activeElement.y =
    position.y;

When scale or rotation is applied, the element's transformed visual bounds can extend beyond its original box. A production editor can use getBoundingClientRect() for more precise transformed-boundary calculations.
The basic clamp shown here is sufficient to demonstrate the positioning workflow.
Applying the Element to Selected Pages
After positioning the element, the user decides which PDF pages should receive it.
The interface provides three options:
Current page only
All pages
Specific pages

Create the controls:


    4. Apply to Pages

    
        
        Current page only
    

    
        
        All pages
    

    
        
        Specific pages
    

    



Read the selected mode:
function getTargetPages() {

    const mode =
        document.querySelector(
            'input[name="applyMode"]:checked'
        ).value;

    if (
        mode ===
        "current"
    ) {

        return [
            currentPage
        ];

    }

    if (
        mode ===
        "all"
    ) {

        return Array.from(

            {
                length:
                    totalPages
            },

            (_, index) =>
                index + 1

        );

    }

    return parsePageRange(
        specificPages.value
    );

}

Parse custom values such as:
1, 3-5, 10

with:
function parsePageRange(
    value
) {

    const pages =
        new Set();

    value
        .split(",")
        .forEach(part => {

            const item =
                part.trim();

            if (!item) {
                return;
            }

            if (
                item.includes("-")
            ) {

                const [
                    start,
                    end
                ] =
                    item
                        .split("-")
                        .map(Number);

                for (
                    let page = start;
                    page <= end;
                    page++
                ) {

                    if (
                        page >= 1 &&
                        page <= totalPages
                    ) {

                        pages.add(page);

                    }

                }

            } else {

                const page =
                    Number(item);

                if (
                    page >= 1 &&
                    page <= totalPages
                ) {

                    pages.add(page);

                }

            }

        });

    return [...pages];

}

The result becomes:
[
    1,
    3,
    4,
    5,
    10
]

This allows a signature or stamp to be placed once and then applied to multiple target pages.
Just keep in mind that page dimensions may differ within the same PDF. Applying the same coordinates across pages works best when those pages use a consistent size and layout.
Applying and Finalizing the PDF
Once the element is created, positioned, styled, and assigned to the correct pages, the user can click Apply & Finalize.
Create the action buttons:


    

    



Get the buttons:
const applyButton =
    document.getElementById(
        "applyButton"
    );

const startOverButton =
    document.getElementById(
        "startOverButton"
    );

Before generating the final PDF, make sure an element exists.
applyButton.addEventListener(
    "click",
    async () => {

        if (!activeElement) {

            alert(
                "Please add a signature, text, or stamp first."
            );

            return;

        }

        const targetPages =
            getTargetPages();

        if (
            targetPages.length === 0
        ) {

            alert(
                "Please select at least one valid page."
            );

            return;

        }

        await generateFinalPdf(
            targetPages
        );

    }
);

The generateFinalPdf() function will handle the actual PDF modification in the next section.
The Start Over button clears the current document and resets the application.
startOverButton.addEventListener(
    "click",
    resetTool
);

Create the reset function:
function resetTool() {

    pdfDocument = null;

    originalPdfBytes = null;

    currentPage = 1;

    totalPages = 0;

    activeElement = null;

    pdfInput.value = "";

    elementLayer.innerHTML = "";

    editorSection.hidden = true;

    resultSection.hidden = true;

    uploadSection.hidden = false;

}

This returns the application to its original upload state.


The interactive editing stage is now complete. Users can create a signature or text element, position it directly over the PDF, adjust its appearance, choose the target pages, and prepare the document for final processing.
Generating the Signed PDF
The element shown over the browser preview hasn't yet been added to the actual PDF. When users click Apply & Finalize, the application loads the original document with PDF-lib and writes the selected signature, text, or stamp onto the target pages.
Start by loading the original PDF bytes:
async function generateFinalPdf(
    targetPages
) {

    const pdfDoc =
        await PDFLib.PDFDocument.load(
            originalPdfBytes.slice()
        );

    const pages =
        pdfDoc.getPages();

}

Before placing the element, we need to convert its browser coordinates into PDF coordinates.
The preview canvas may be displayed at a different size from the actual PDF page. The coordinate systems also use different Y-axis origins.
For each target page, calculate the scale:
const {
    width: pdfWidth,
    height: pdfHeight
} = page.getSize();

const scaleX =
    pdfWidth /
    pdfCanvas.width;

const scaleY =
    pdfHeight /
    pdfCanvas.height;

Convert the preview position:
const pdfX =
    activeElement.x *
    scaleX;

const pdfY =
    pdfHeight -
    (
        activeElement.y +
        activeElement.element.offsetHeight
    ) * scaleY;

This conversion maps the element from the browser's top-left coordinate system to the PDF page's coordinate system.
Embedding a Signature
Drawn, typed, and uploaded signatures are all represented as images by the time they reach the final processing stage.
Convert the signature data URL into bytes:
async function dataUrlToBytes(
    dataUrl
) {

    const response =
        await fetch(dataUrl);

    return await response.arrayBuffer();

}

Embed the signature image:
const signatureBytes =
    await dataUrlToBytes(
        activeElement.source
    );

const signatureImage =
    await pdfDoc.embedPng(
        signatureBytes
    );

If uploaded JPEG signatures are supported, the application should preserve the original image format and use embedJpg() when appropriate.
Calculate the final dimensions:
const previewWidth =
    activeElement
        .element
        .offsetWidth *
    activeElement.scale;

const previewHeight =
    activeElement
        .element
        .offsetHeight *
    activeElement.scale;

const finalWidth =
    previewWidth *
    scaleX;

const finalHeight =
    previewHeight *
    scaleY;

Then draw the signature:
page.drawImage(
    signatureImage,
    {
        x: pdfX,

        y:
            pdfHeight -
            (
                activeElement.y *
                scaleY
            ) -
            finalHeight,

        width:
            finalWidth,

        height:
            finalHeight,

        rotate:
            PDFLib.degrees(
                activeElement.rotation
            ),

        opacity:
            activeElement.opacity
    }
);

The same processing logic works whether the signature was drawn, typed, or uploaded because all three methods produce an image element before finalization.
Adding Text or a Stamp
Text and preset stamps are written directly onto the PDF page.
First, convert the selected color from hexadecimal to RGB values.
function hexToRgb(
    hex
) {

    const value =
        hex.replace(
            "#",
            ""
        );

    return {

        r:
            parseInt(
                value.substring(0, 2),
                16
            ) / 255,

        g:
            parseInt(
                value.substring(2, 4),
                16
            ) / 255,

        b:
            parseInt(
                value.substring(4, 6),
                16
            ) / 255

    };

}

Apply the text:
const color =
    hexToRgb(
        activeElement.color
    );

page.drawText(
    activeElement.text,
    {
        x:
            activeElement.x *
            scaleX,

        y:
            pdfHeight -
            (
                activeElement.y *
                scaleY
            ) -
            activeElement.fontSize,

        size:
            activeElement.fontSize *
            scaleY,

        color:
            PDFLib.rgb(
                color.r,
                color.g,
                color.b
            ),

        rotate:
            PDFLib.degrees(
                activeElement.rotation
            ),

        opacity:
            activeElement.opacity
    }
);

After processing every target page, save the modified document:
const finalPdfBytes =
    await pdfDoc.save();

const finalPdfBlob =
    new Blob(
        [finalPdfBytes],
        {
            type:
                "application/pdf"
        }
    );

await showFinalPreview(
    finalPdfBlob
);

At this point, the selected signature, text, or stamp has been added to the generated PDF.
Previewing the Final PDF
Before downloading the document, the application displays the completed PDF in a separate preview area.
This allows users to confirm that the element appears on the correct page and in the expected position.
Load the generated file with PDF.js:
let finalPdfDocument = null;

let finalPage = 1;

async function showFinalPreview(
    blob
) {

    const bytes =
        await blob.arrayBuffer();

    finalPdfDocument =
        await pdfjsLib
            .getDocument({
                data: bytes
            })
            .promise;

    finalPage = 1;

    editorSection.hidden =
        true;

    resultSection.hidden =
        false;

    await renderFinalPage(
        finalPage
    );

}

Render the current result page:
async function renderFinalPage(
    pageNumber
) {

    const page =
        await finalPdfDocument
            .getPage(
                pageNumber
            );

    const viewport =
        page.getViewport({
            scale: 1.4
        });

    finalCanvas.width =
        viewport.width;

    finalCanvas.height =
        viewport.height;

    await page.render({

        canvasContext:
            finalCanvas
                .getContext("2d"),

        viewport

    }).promise;

    finalPageInfo.textContent =
        `Page ${pageNumber} of ${finalPdfDocument.numPages}`;

}

Previous and next controls can use the same navigation pattern as the original PDF preview.


Renaming and Downloading the Final PDF
After reviewing the processed document, users can rename the file before downloading it.
For example:
document_signed.pdf

Create the filename input:


Make sure the filename has the correct extension:
function getOutputFilename() {

    let filename =
        outputFilename
            .value
            .trim();

    if (!filename) {

        filename =
            "document_signed.pdf";

    }

    if (
        !filename
            .toLowerCase()
            .endsWith(".pdf")
    ) {

        filename += ".pdf";

    }

    return filename;

}

The result section can also display the total page count and generated file size.
function formatFileSize(
    bytes
) {

    if (
        bytes <
        1024 * 1024
    ) {

        return (
            bytes / 1024
        ).toFixed(2) + " KB";

    }

    return (
        bytes /
        1024 /
        1024
    ).toFixed(2) + " MB";

}

Update the file information:
filePageCount.textContent =
    `Total Pages: ${finalPdfDocument.numPages}`;

fileSize.textContent =
    `File Size: ${
        formatFileSize(
            finalPdfBlob.size
        )
    }`;

Download the file using a temporary object URL:
downloadButton.addEventListener(
    "click",
    () => {

        const url =
            URL.createObjectURL(
                finalPdfBlob
            );

        const link =
            document.createElement(
                "a"
            );

        link.href =
            url;

        link.download =
            getOutputFilename();

        link.click();

        URL.revokeObjectURL(
            url
        );

    }
);



After downloading, the Start Over button resets the application so another PDF can be processed.


Demo: How the PDF Signature Tool Works
Let's walk through the complete workflow from upload to download.
Step 1: Upload the PDF
Users begin by dragging a PDF into the upload area or clicking Select PDF.
The browser reads the document and prepares it for local processing.


Step 2: Preview and Navigate the Document
After upload, the current page appears in the PDF preview.
Previous and next controls allow users to navigate through multi-page documents and find the page where an element needs to be added.


Step 3: Choose What to Add
The user chooses between Signature and Text/Stamp.
This determines which creation controls appear in the editor.


Step 4: Create the Signature
If Signature is selected, users can choose Draw, Type, or Upload.
Drawing works directly inside the signature canvas. The Type option creates a signature-style element from entered text, while Upload accepts an existing signature image.


Step 5: Add Custom Text or a Preset Stamp
Instead of a signature, users can select Text/Stamp.
They can enter custom content or choose a preset such as APPROVED, CONFIDENTIAL, DRAFT, or PAID.


Step 6: Position and Style the Element
The created element appears over the PDF preview.
Users can drag it to the required position and adjust properties such as scale, rotation, opacity, X position, and Y position.
Text elements also support configurable font size and color.


Step 7: Choose the Target Pages
The element can be applied to the current page, every page, or a specific page selection.
For example:
1, 3-5, 10



This is useful when the same stamp or document label needs to appear on several pages.
Step 8: Apply and Finalize
After checking the element and target pages, users click Apply & Finalize.
The browser converts the preview position into PDF coordinates and generates the modified document.


Step 9: Preview the Completed PDF
The generated document appears in a final preview.
Users can navigate through the pages and verify that the signature, text, or stamp appears correctly before downloading.


Step 10: Rename and Download
The final section allows users to change the output filename and review the total number of pages and file size.
Clicking Download saves the generated PDF locally.


Afterward, Start Over clears the session and returns to the upload interface.
Handling Signature Transparency
Uploaded signatures often look best when the background is transparent.
A transparent PNG contains only the visible signature strokes, allowing the original PDF content to remain visible around the signature.
A JPEG image, by comparison, usually includes a solid background. If the image was scanned from white paper, placing it on a colored PDF area may create a visible white rectangle.
For uploaded signatures, transparent PNG files are therefore usually the better option.
The same principle applies to drawn and typed signatures. When converting a canvas to PNG, avoid filling the canvas with a background color unless that background is intentionally required.
const signatureImage =
    signatureCanvas.toDataURL(
        "image/png"
    );

The transparent canvas can then be embedded directly into the PDF.
Important Notes and Common Mistakes
One common mistake is assuming that the browser preview and the actual PDF use identical coordinates.
Always calculate the relationship between the canvas dimensions and the target PDF page before placing the final element.
const scaleX =
    pdfWidth /
    pdfCanvas.width;

const scaleY =
    pdfHeight /
    pdfCanvas.height;

Another issue occurs when the same element is applied to pages with different dimensions. A position that looks correct on an A4 page may not appear in the same visual location on a landscape or differently sized page.
Uploaded signature images should also be validated before processing.
const allowedTypes = [
    "image/png",
    "image/jpeg"
];

if (
    !allowedTypes.includes(
        file.type
    )
) {

    alert(
        "Please upload a PNG or JPEG image."
    );

    return;

}

Very large image files should be resized before embedding to avoid unnecessarily increasing the final PDF size.
Users should also review the completed document before downloading it. Rotation, scaling, or coordinate conversion errors are much easier to identify in the final preview than after the file has already been shared.
Finally, remember that this project adds a visual electronic signature to a PDF. It does not create a certificate-based cryptographic digital signature or provide automatic identity verification.
Conclusion
In this tutorial, you built a browser-based PDF Signature Tool using JavaScript.
You learned how to upload and preview PDF documents, navigate between pages, create signatures by drawing, typing, or uploading an image, add custom text and preset stamps, position elements directly over a PDF preview, adjust their appearance, choose target pages, and generate the completed document with PDF-lib.
You also learned how browser coordinates are converted into PDF coordinates and why signature transparency matters when embedding images into a document.
The final workflow allows users to preview the completed PDF, rename the output file, review its page count and size, and download it directly from the browser.
You can explore the complete workflow using the PDF Signature Tool.
The project can be extended further with multiple elements per page, reusable signature profiles, date fields, initials, custom fonts, signature removal before finalization, or certificate-based digital signing through a dedicated signing infrastructure.