Available in JavaScript Ruby Python Java PHP CoffeeScript Go and for Node.js .NET
Generate short hashes from numbers (like YouTube and Bitly).
obfuscate database IDs · use them as forgotten password hashes · invitation codes · store shard numbers
Hashids was designed for use in URL shortening, tracking stuff, validating accounts or making pages private (through abstraction). Instead of showing items as 1, 2, or 3, you could show them as b9iLXiAa, EATedTBy, and Aaco9cy5. Hashes depend on your salt value.
One of the main reasons it's beneficial to have hashes instead of numbers is because you might not want to disclose your count, or let users navigate by incrementing the numbers. If you are using integers to keep track of users, it's very easy to see how many users you have or who joined last. Having hashes solves that problem.
To encrypt a simple number:
To decrypt a hash:
To encrypt several numbers, pass them all at once:
Decryption is done the same way:
Hashids supports personalizing your hashes by accepting a salt value. If you don't want others to decrypt your hashes, provide a unique string to the constructor.
If you change the salt, the generated hash changes:
There's not a way to guess the correct numbers behind the hash without knowing the salt value first.
Your salt string does not have to be too long to be random. It's a balance between speed and randomness, so if you pick something between 6 and 32 characters your hashes should be randomized pretty well already.
By default, hashes are going to be the shortest possible. One reason you might want to increase the hash length is to obfuscate how large the number behind the hash is.
This is done by passing the minimum hash length to the constructor (for example 16):
That way even though your number is small, the hash is padded with extra characters to make it seem longer.
It's now at least 16 characters long. Note that this is a minimum hash length - produced hashes can end up being longer.
Not passing a minimum hash length, we'll get a regular short hash:
It's also possible to set a custom alphabet for your hashes.
The default alphabet contains all lowercase and uppercase letters and numbers:
a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0
If you wish to have only lowercase letters in your hashes, you could pass in the following custom alphabet:
With latest versions of Hashids, your alphabet should contain at least 16 characters.
This code was written with the intent of placing generated hashes in visible places - like the URL.
Therefore, the algorithm tries to avoid generating most common English curse words by never placing the following letters next to each other:
c, C, s, S, f, F, h, H, u, U, i, I, t, T
If you are using a relational database, you could store hashes for each row, so you could select by them. But then you'd need to index them to speed up reads.
Since all primary keys are already indexed, you could instead encrypt/decrypt your primary keys on the fly and select by them.
If you have a complex clustered system, you could encrypt several numbers at once. For example, your shard number and your primary key 2, 1337 and turn them into a single hash: zKIa5e. Upon decryption, you could do the reverse: decrypt the hash and get the numbers, jump to the right shard, select by primary id — and you have the right record.
There are no collisions. Your generated hashes should be unique.
A true cryptographic hash cannot be decrypted. However, to keep things simple the word hash is used loosely to refer to the random set of characters that are generated. Like a YouTube hash.
There are many ways to contribute. Although Hashids has been ported to a few languages, there are still many more: C, C++, Objective-C, Scala, Erlang, Perl, Clojure, Groovy, Haskell, Lolcode etc etc... If you'd like your port added to the list, please message @IvanAkimov.
All main libraries are hosted on Github. If you see a bug in code, or have an improvement you'd like to add, please open an issue on Github for the correct library.
You can also turn Hashids into a plugin for your favorite framework. If a link is missing, ping to add it.
All Hashids libraries are under MIT License. You can use them in open source projects and commercial products. Don't break the Internet. Kthxbye.