# pad

> Left and right string padding

Latest version **3.3.0** (published 2024-09-29) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install pad
pnpm add pad
yarn add pad
bun add pad
```

## Health

**Score 48/100 (D)** — status: stable.

Positive: has types package; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.3.0 |
| Published | 2024-09-29 |
| First published | 2011-11-14 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | separate (@types/pad) |
| Module format | ESM |
| Node | >= 4.0.0 |
| Dependencies | 1 |
| Unpacked size | 58.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 42 |
| Author | David Worms |
| Maintainers | david |
| Keywords | pad, string |

## Links

- npm: https://www.npmjs.com/package/pad
- Repository: https://github.com/adaltas/node-pad
- Issues: https://github.com/adaltas/node-pad/issues
- npm.io page: https://npm.io/package/pad

## Dependencies (1)

- [wcwidth](https://npm.io/package/wcwidth.md) ^1.0.1

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 3.3.0 (latest) — 2024-09-29
- 3.2.0 — 2019-05-20
- 3.1.0 — 2019-05-13
- 3.0.1 — 2019-05-03
- 3.0.0 — 2019-05-03
- 2.3.0 — 2019-04-01
- 2.2.3 — 2019-03-29
- 2.2.2 — 2019-01-10
- 2.2.1 — 2018-08-23
- 2.2.0 — 2018-08-23
- 2.1.0 — 2018-05-11
- 2.0.3 — 2017-11-08
- 2.0.2 — 2017-11-08
- 2.0.1 — 2017-10-09
- 2.0.0 — 2017-10-09
- … 17 more at https://npm.io/package/pad/versions

## README

# Node.js pad

[![Build Status](https://secure.travis-ci.org/adaltas/node-pad.png)](http://travis-ci.org/adaltas/node-pad)

Node Pad is a simple and elegant function to pad strings in both left and right directions. It is written in Typescript and it support both CommonJS and ESM.

## Usage

The API is quite simple:

```javascript
import pad from "pad";
// Or const pad = require("pad")
pad("pad", 5); // "pad  "
pad(5, "pad"); // "  pad"
pad("pad", 5, "+"); // "pad++"
pad(5, "pad", "+"); // "++pad"
```

For TypeScript users, the type definition files are located in "./lib/index.d.ts" and declared inside the "package.json" file.

## Bundles

Node Pad comes in multiple flavours depending on your target environment:

- CommonJS: `dist/pad.cjs.js`  
  Bundle used by Node.js and compatible with ES5. It is declared inside the `package.json` by the `main` property and used by default with `require("pad")` in a Node.js environment.
- ES module: `dist/pad.esm.js`  
  Bundle using the ECMAScript standard defined in ES6 for working with modules. The path to the ES module is declared inside the `package.json` by the `module` property for ESM-aware tools like [Rollup](https://rollupjs.org) and [webpack 2+](https://webpack.js.org/).

The CommonJS syntax to import Node Pad is:

```js
const pad = require("pad/dist/pad.cjs.js");
// Or simply
const pad = require("pad");
```

While the ES Modules syntax is:

```js
import pad from "pad/dist/pad.esm.js";
// Or for ESM-aware tools
import pad from "pad";
```

## Options

Options are provided as a third argument and are all optional. A string argument
it is interpreted as the "char" option. Accepted options include:

- `char` (string)  
  The character used to fill the gap.
- `colors` (boolean)  
  Ajust to hidden terminal color characters, you may also use `require 'pad/lib/colors'` to avoid passing this option.
- `strip` (boolean)  
  Remove characters from text if length smaller than text length, default to "false".
- `fixed_width` (boolean)  
  An optimization option to disable the usage of the wcwdith package to handle the discovery of characters using more than one column for display.
  one column to display
- `wcwidth_options` (object)  
  Options passed to the wcwidth package used to calculate the display width of
  characters using more than one column.

## Left padding: `pad(length, text, [options])`

Left padding occurs when the first argument is a number and the second
argument is a string.

```javascript
import pad from "pad";
pad(5, "pad", "-").should.eql("--pad");
```

## Right padding: `pad(text, length, [options])`

Right padding occurs when the first argument is a string and the second
argument is a number.

```javascript
import pad from "pad";
pad("pad", 6).should.eql("pad   ");
```

## Installing

Starting with version 1.1.0, Node pad rely on Node.js 4.0.0 or more recent.
Stick to version 1.0.x if using an older version of Node.js.

Via [npm](http://github.com/isaacs/npm):

```bash
npm install pad
```

Via git (or downloaded tarball), copy or link the project from a discoverable
Node.js directory:

```bash
git clone http://github.com/adaltas/node-pad.git
```

## Testing

Clone the repo, install the development dependencies and run the suite:

```bash
git clone http://github.com/adaltas/node-pad.git .
npm install
make test
```

## Contributors

The project is sponsored by [Adaltas](https://www.adaltas.com) based in Paris, France. Adaltas offers support and consulting on distributed systems, big data and open source.

---
_Source: https://npm.io/package/pad · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._