Add Page Numbers Guide

Learn to develop your own solution to automatically number PDF pages by integrating with iLovePDF’s REST API.

Remember that in order to use our Tool Guides, you need to have previous knowledge about the basics to processing a PDF with our REST API. We strongly recommend that you read the Processing a PDF guide before starting this one.

Basic page numbers

You can add page numbers to your PDF files as shown in this code:

Basic page numbers

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Add files to task for upload
$file1 = $myTask->addFile('path/to/file1_name.pdf');
// Execute the task
$myTaskPageNumbers>execute();
// Download the package files
$myTaskPageNumbers->download();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Add files to task for upload
var file = taskPageNumbers.AddFile("path/to/file/file1_name.pdf");
// Execute the task
taskPageNumbers.Process();
// Download the package files
taskPageNumbers.DownloadFile();

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Add files to task for upload
file1 = my_task_page_numbers.add_file 'path/to/file1_name.pdf'
# Execute the task
my_task_page_numbers.execute
# Download the package files
my_task_page_numbers.download

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process();
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

By using a page number task as a process tool you will add numbers to your PDF pages.

Many settings can be customized with the advanced options explained in next sections.

Advanced page numbers

Do not number first page

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Set your tool options
$myTaskPageNumbers->setFirstCover(true);
// Execute the task
$myTaskPageNumbers>execute();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Set your tool options
var parameters = new PageNumbersParams (
            {
                FirstCover  = true
            };
// Execute the task
taskPageNumbers.Process(parameters);

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Set your tool options
my_task_page_numbers.first_cover = true
# Execute the task
my_task_page_numbers.execute

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process({ first_cover: true });
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

first_cover is a useful property for books or magazines and allows you to avoid numbering the first page of your document. It is recommended to combine this property with first_cover to set from which number you want to begin your PDF page numbers.

Default: true

Set starting number

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Set your tool options
$myTaskPageNumbers->setStartNumber(2);
// Execute the task
$myTaskPageNumbers->execute();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Set your tool options
var parameters = new PageNumbersParams (
            {
                StartingNumber   = 2
            };
// Execute the task
taskPageNumbers.Process(parameters);

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Set your tool options
my_task_page_numbers.start_number = 2
# Execute the task
my_task_page_numbers.execute

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process({ starting_number: 2 });
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

starting_number will let you set from which number the page numbering will start and it is recommended to combine this with first_cover and pages to set which pages will be numbered.

Default: 1

Pages to number

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Set your tool options
$myTaskPageNumbers->setPages('3-end');
// Execute the task
$myTaskPageNumbers>execute();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Set your tool options
var parameters = new PageNumbersParams (
            {
                Pages   = "3-end"
            };
// Execute the task
taskPageNumbers.Process(parameters);

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Set your tool options
my_task_page_numbers.pages = '3-end'
# Execute the task
my_task_page_numbers.execute

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process({ pages: '3-end' });
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

pages has plenty of options to be numbered. See them:

all
3-end
1-3,4-9
-2-end
3-234

Default: all

Set numbers font format

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Set your tool options
$myTaskPageNumbers->setFontFamily('courier');
$myTaskPageNumbers->setFontSize(18);
$myTaskPageNumbers->setFontColor('#ffffff');
// Execute the task
$myTaskPageNumbers>execute();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Set your tool options
var parameters = new PageNumbersParams (
            {
                FontFamily = "courier",
                FontSize = 18,
                FontColor = "#ffffff"
            };
// Execute the task
taskPageNumbers.Process(parameters);

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Set your tool options
my_task_page_numbers.font_family = 'courier'
my_task_page_numbers.font_size = 18
my_task_page_numbers.font_color = '#ffffff'
# Execute the task
my_task_page_numbers.execute

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process({
        font_family: 'Verdana',
        font_size: 18,
        font_color: '#ffffff',
    });
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

font_family, font_size and font_color are properties to customize the page numbers font format. The font_family property changes which font will be used, font_size changes the font size, and font_color changes the color of the numbers.

Default: Arial Unicode MS 14px #000000

Format of page number

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Set your tool options
$myTaskPageNumbers->setText('Page {n} of {p}');
// Execute the task
$myTaskPageNumbers>execute();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Set your tool options
var parameters = new PageNumbersParams (
            {
                Text = "Page {n} of {p}"
            };
// Execute the task
taskPageNumbers.Process(parameters);

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Set your tool options
my_task_page_numbers.text = 'Page {n} of {p}'
# Execute the task
my_task_page_numbers.execute

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process({ text: 'Page {n} of {p}' });
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

It is possible to set the page number format and add strings to it concatenated with variables using text. In the code example, the page number content is: "Page N of P" where N is the number of the current page and P is the total number of pages in the PDF document.

Default: N

Vertical position of numbers

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Set your tool options
$myTaskPageNumbers->setVerticalPosition('top');
// Execute the task
$myTaskPageNumbers->execute();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Set your tool options
var parameters = new PageNumbersParams (
            {
                VerticalPosition  = VerticalPositions.top
            };
// Execute the task
taskPageNumbers.Process(parameters);

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Set your tool options
my_task_page_numbers.vertical_position = 'top'
# Execute the task
my_task_page_numbers.execute

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process({ vertical_position: 'top' });
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

vertical_position allows you to set the vertical position of page numbers to the top or the bottom of the page. Note that there will not be a margin. In order to do this, use vertical_position_adjustment.

Default: bottom

Vertical position adjustment of numbers

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Set your tool options
$myTaskPageNumbers->setVerticalAdjustPosition(20);
// Execute the task
$myTaskPageNumbers->execute();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Set your tool options
var parameters = new PageNumbersParams (
            {
                VerticalPositionAdjustment  = 20
            };
// Execute the task
taskPageNumbers.Process(parameters);

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Set your tool options
my_task_page_numbers.vertical_adjust_position = 20
# Execute the task
my_task_page_numbers.execute

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process({ vertical_position_adjustment: 20 });
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

vertical_position_adjustment applies a displacement of pixels from the standard vertical position. This value can be positive or negative. So watch out, because if you place the number at the bottom of the page with vertical_position and then apply a huge pixel displacement, the page number will be off the page!

Default: 0

Horizontal position of numbers

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Set your tool options
$myTaskPageNumbers->setHorizontalPosition('left');
// Execute the task
$myTaskPageNumbers->execute();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Set your tool options
var parameters = new PageNumbersParams (
            {
                HorizontalPosition   = HorizontalPositions.left
            };
// Execute the task
taskPageNumbers.Process(parameters);

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Set your tool options
my_task_page_numbers.horizontal_position = 'left'
# Execute the task
my_task_page_numbers.execute

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process({ horizontal_position: 'left' });
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

horizontal_position allows you to set the horizontal position of page numbers to the left, center or right of the page. Take note that left and right positions will be affected by setting facing_pages as you will see in its description.

Default: center

Horizontal position adjustment of numbers

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Set your tool options
$myTaskPageNumbers->setHorizontalAdjustPosition(20);
// Execute the task
$myTaskPageNumbers>execute();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Set your tool options
var parameters = new PageNumbersParams (
            {
                HorizontalPositionAdjustment = 20
            };
// Execute the task
taskPageNumbers.Process(parameters);

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Set your tool options
my_task_page_numbers.horizontal_adjust_position = 20
# Execute the task
my_task_page_numbers.execute

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process({ horizontal_position_adjustment: 20 });
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

horizontal_position_adjustment will displace the amount of pixels set in params, from its defined horizontal position. This value can be positive or negative so be careful- If you have your number placed to the right with horizontal_position and horizontal_position_adjustment set to a large positive value, you will place your number outside of the page!

Default: 0

Add number to facing pages

// Create a new task
$myTaskPageNumbers = $ilovepdf->newTask('pagenumber');
// Set your tool options
$myTaskPageNumbers->setFacingPages(true);
// Execute the task
$myTaskPageNumbers->execute();

// Create a new task
var taskPageNumbers = api.CreateTask<PageNumbersTask>();
// Set your tool options
var parameters = new PageNumbersParams (
            {
                FacingPages  = true
            };
// Execute the task
taskPageNumbers.Process(parameters);

# Create a new task
my_task_page_numbers = ilovepdf.new_task :pagenumber
# Set your tool options
my_task_page_numbers.facing_pages = true
# Execute the task
my_task_page_numbers.execute

const task = ilovepdf.newTask('pagenumber') as PageNumberTask;

task.start()
.then(() => {
    return task.addFile('path/to/file1_name.pdf');
})
.then(() => {
    return task.process({ facing_pages: true });
})
.then(() => {
    return task.download();
})
.then((data) => {
    fs.writeFileSync('path/to/local/file_name.pdf', data);
});

With the facing_pages property you can set your PDF numbering in facing mode, like a book or a magazine. This only takes effect when combined with horizontal_position left or right and will place all page numbers mirrored between pages where left will place numbers to the inside and right to the outside of the page. See the example below for a better understanding:

Default: false