Avatars That Don't Look Blurry: Upload and Cropping for Your Vibe Project
Avatars are the smallest unit of trust in a product — and everyone sees it when they go wrong. Using a fictional baking community: three size tiers, cropper design, a two-stage compression pipeline, default avatars, moderation, and a 12-item checklist.

Why avatars deserve serious work: the smallest unit of trust in your product
An avatar is the smallest image in a product — and the most-seen one. When a user posts ten times in a community, their avatar is seen ten times; when they say one sentence in a group chat, the avatar appears once. A blurry avatar, an avatar cropped in half, an avatar turned sideways — users won't think "this avatar feature is rough," they will think "this product is unreliable." Avatars work like that: done right, nobody praises them; done wrong, everyone notices.
This guide uses one fictional example throughout: a baking community app called "Weekend Baking Circle," where users post their bakes, organize offline baking meetups, and comment on each other's work. The product, numbers, and dialogues in the example are all fictional — they exist to make the reasoning concrete, not to report real operating data. As you read, swap "Baking Circle" for your own product; the logic is the same.
An avatar feature looks simple, but it is really four small features combined: picking an image, cropping it, compressing and uploading it, and displaying it. Each step has its own pitfalls, and if any one of them fails, what users end up seeing is the same blurry face. This guide walks through the four steps in order, and ends with an acceptance checklist.
Set the sizes first: original, crop, and display are three separate numbers
The first step in building avatars is not writing code — it is deciding three sets of numbers: how big the original can be, how big the cropped version is stored, and how big the display sizes are. Get these wrong and everything after is rework.
The original: photos users pick from their camera roll are now routinely 4000×3000 and 3.5MB or more. Should the original be uploaded to the server as-is? No. Compress it on the phone first, before upload: long edge to 1024 pixels, quality 85%, and a 3.5MB photo comes down to around 200KB — plenty sharp for an avatar. This step saves the user's data and your bandwidth, and it is the first line of defense for upload success rates.
The crop: store one square cropped version at 512 pixels on a side as the "avatar master" on the server. Why 512? Because the largest size you will display is usually no more than 192 pixels (the big avatar on a profile page), and 512 leaves 2.6x headroom, so it stays sharp on retina screens. Going up to 1024 quadruples the file size with no visible difference in sharpness — pure waste.
Display: the same avatar master appears in at least three sizes in the product: 96×96 on profile pages, 48×48 in lists and comment threads, and 32×32 in group chats and message bubbles. The right approach is for the server to generate all three thumbnails at upload time, and for the front end to fetch the size the scene needs — don't make the front end shrink a 512-pixel image into a 32-pixel slot. That wastes data and is a source of stuttering on low-end phones.
Format needs deciding too: JPEG is the default, with the best compatibility; WebP can be about 25% smaller, but only if your image service and clients both support it; PNG only makes sense when a user uploads an image with a transparent background, which almost never matters for avatars — don't store PNG by default. Animated avatars (GIFs) should simply be banned: one flashing avatar appearing ten times in a comment thread is torture for every reader.
How to build the cropper: let users see the result, not guess it
Cropping is the step that most affects the experience, and it deserves the most care. Start with the crop frame: a square by default, 80% of the screen width, centered; outside the frame, a translucent mask, so users can see at a glance that "inside the frame stays, outside gets cut." Gestures should support three kinds: one finger drags to move the frame, two fingers pinch to zoom the image, and double-tap resets to the start. A cropper that only supports dragging and not zooming leaves users helpless the moment they have a tall group photo.
A circular preview must update in real time. Avatars are usually displayed as circles in the product, so the four corners of the square crop get cut off — a face positioned nicely in the square can lose half a forehead once the circle cuts in. The right approach is a small circular preview next to the crop frame that updates as the user drags: what you see is what you get. It costs almost nothing to build, and the effect is direct: complaints about "my avatar got cut in half" drop sharply after launch.
One more human touch: don't rigidly center the default crop area. Photos taken on phones often have the person off-center; in a group photo, the user wants to crop themselves, not whoever happens to be in the middle. Simple face detection solves this: once a face is detected, start the crop frame over the face area. If face detection is out of reach, at least offer "tap the image and the crop frame jumps there." Don't make users drag a millimeter at a time from the edge of the screen.
In the Baking Circle example, a user uploads a group photo from a baking class and wants to crop themselves out as an avatar. Without face detection, the default frame sits in the middle of the photo, framing the teacher standing in the center; the user has to drag for ages to frame themselves standing at the edge. With face detection, the frame starts on the closest face, and the user just taps confirm.
The compression pipeline: compress on the client first, then on the server — never the other way around
Avatar upload has two compression stages, and the order cannot be reversed. Stage one runs on the client: after the user picks and crops the image, compress it locally before upload — long edge 1024, quality 85%. The point is to make the upload itself fast and reliable: a 3.5MB original takes 20 seconds to upload on the subway and fails often; at 200KB it finishes in 3 seconds, even on a weak connection. Use the system's native image APIs for client-side compression, never a hand-rolled algorithm — the native APIs have hardware acceleration and are much faster.
Stage two runs on the server: once the image arrives, generate the 512-pixel avatar master and the 96, 48, and 32-pixel thumbnails, converting everything to JPEG (or WebP) at quality 82%. Server-side compression can be a little more aggressive than the client's, because by then the image is already a cropped square with lower information density, and heavier compression is invisible. The two stages together turn a 3.5MB original into a 48KB avatar master plus three thumbnails of a few KB each — under 60KB in total.
There is one classic pitfall in this pipeline that deserves its own paragraph: EXIF orientation. Photos taken on an iPhone may store their pixels sideways, relying on an EXIF orientation tag to tell viewers to "rotate 90 degrees before displaying." If any step in your upload chain drops the EXIF data without applying the rotation, the user's avatar ends up sideways. The fix is to rotate the pixels to the correct orientation during client-side compression, so nothing downstream depends on EXIF again. When testing, try three kinds of iPhone photos — portrait, landscape, and front-camera selfies — and don't let a single sideways avatar through.
There is one more format pitfall: HEIC. iPhones save photos in HEIC by default — small files, great quality — but many backend image libraries and older browsers don't support it. The right approach is to convert HEIC to JPEG during client-side compression, before upload; don't send HEIC to the server and convert there. Server-side HEIC conversion needs an extra decoder library, and when it breaks, it is hard to pin down.
Default avatars: don't use a gray silhouette — use an initial on a color
Not every user uploads an avatar right away. What shows in the avatar slot for a newly registered user decides whether your community looks "alive" or "empty" at first glance. The worst choice is a gray silhouette: ten gray silhouettes in a row make a comment thread look like an unfinished building. A better choice is an initial avatar: the first character of the user's nickname (the first Chinese character, or the first capital letter in English) on a colored circle.
Initial avatars have three rules. First, assign the color from a hash of the user ID, so the same user always gets the same color — people can recognize someone from the color alone at a distance. Second, keep a pool of 8 to 10 colors, distinct and moderately saturated: nothing too pale (invisible on a white background) and nothing fluorescent. Third, handle Chinese and English separately: one Chinese character at 44 pixels in a 96-pixel avatar fits perfectly, while two English letters need to drop to 36 pixels or they overflow.
In the Baking Circle example, a new user "A-May" registers without uploading a photo, and the system gives her a mint-green circle with a white "A"; "Old Chen the Oven Repairman" gets a warm orange circle with a white "C." When the two meet for the first time in a comment thread, the colors and characters are different, and anyone can tell them apart at a glance. When they later upload real photos, the initial avatars step aside automatically, and users notice nothing at all.
Moderation and safety: avatars are the closest entry point for porn and ads
Avatars are one of the easiest places in a product to abuse: pornographic images, QR-code ads, and politically sensitive content all like to hide in avatars — because avatars are small, moderation often misses them, and few people bother to report them. For an avatar feature, moderation is not a "later" item; it has to exist on day one.
The first layer is machine moderation: call an off-the-shelf image moderation service and check every uploaded avatar for pornography, violence, and QR codes. Block pornography and violence outright, with a message like "This image doesn't meet community standards, please choose another one"; for QR codes, don't block immediately — many users' avatars legitimately contain their own WeChat QR code in some form — but log it for manual spot checks. Machine moderation is cheap and accurate enough; don't train your own model from scratch.
The second layer is a rate limit: one account can change its avatar at most 3 times a day, with a message like "You've changed it quite a few times today, come back tomorrow." This rule is not aimed at normal users — it targets accounts that use the avatar slot for ads: they register dozens of accounts and rotate ad-carrying avatars, and a rate limit raises their cost by an order of magnitude. Normal users rarely change avatars more than a few times a year; a limit of 3 a day never touches them.
The third layer is a report entry: from any user's avatar, there must be a "Report avatar" option, with human review within 24 hours. The deeper the report entry is buried, the longer bad avatars survive. And tell the reporter the outcome: "The avatar you reported has been handled, thank you" — that sentence is what keeps people reporting. Nobody reports into a black hole twice.
One picture: how a 3.5MB original becomes a 48KB avatar

This chart shows the measured averages from the fictional Baking Circle example's first month after launch: the user's original photo, 4000×3000, about 3,584KB; after on-device compression, long edge 1024, about 200KB; cropped to a 512×512 square, uncompressed about 768KB; the final JPEG avatar master at quality 82%, about 48KB; the three thumbnails (96, 48, 32) together under 12KB. From 3,584KB to 48KB, the file shrinks by 98.7%, and at a 96-pixel display size the human eye cannot tell any difference.
The point of this chart is that the bulk of the savings happens in the on-device compression step (3,584 down to 200), not on the server. Many teams only compress on the server, so users upload a 3.5MB original on the subway, the upload breaks halfway, and the retry starts from scratch — upload success rates suffer badly. Compress first, then upload: that is the lifeline of avatar upload success.
The funnel and the acceptance checklist: five numbers to watch in the first month
The fictional Baking Circle example's first-month funnel is: of 1,000 upload attempts, 962 passed format validation (96.2%), 901 completed cropping (93.7%), 874 finished compression and upload (97.0%), and 812 avatars were still in use after seven days (92.9%). Overall, the conversion from tapping "change avatar" to still using the avatar seven days later is 81.2%. The biggest single-step loss is in "completed cropping" (901 out of 962), which means the cropper still needs polish; the smallest is in "compression and upload succeeded," which means the compress-first strategy is working.
The pre-launch acceptance checklist has 12 items. One, when the original's long edge exceeds 1024, the client compresses before upload. Two, the crop frame defaults to a square at 80% of screen width, supporting drag, pinch zoom, and double-tap reset. Three, the circular preview updates in real time. Four, face detection positions the initial crop frame, with tap-to-position as a fallback. Five, the server generates the 512 master and the 96, 48, and 32 thumbnails. Six, EXIF orientation is corrected during client-side compression, tested with iPhone portrait, landscape, and front-camera selfies. Seven, HEIC is converted to JPEG on the client before upload. Eight, animated avatars are banned by default. Nine, default avatars use an initial on a fixed color, with 8 to 10 colors. Ten, machine moderation covers pornography, violence, and QR codes. Eleven, no more than 3 avatar changes per day. Twelve, every user's avatar page has a report entry, handled by a human within 24 hours.
How to verify: take five real users and walk the full flow on three phones (an iPhone, an Android flagship, and a budget Android), timing every step; then test ten "difficult" photos specifically: tall group shots, backlit portraits, faces in sunglasses, pet photos, and pure-text screenshots. Ship only when all 12 items pass.
Common mistakes: almost every team makes at least one of these five
The first mistake is making the front end shrink the 512-pixel master into a 32-pixel slot. The result is stuttering lists on low-end phones and wasted data. The right approach is for the server to pre-generate three thumbnail sizes, and for the front end to fetch the size the scene needs — a 32-pixel slot loads only a 32-pixel image.
The second mistake is a crop frame that defaults to the center. In a group photo, the user stands at the edge while the frame lands on a stranger in the middle. Add face detection, or at least allow tap-to-position — don't make users drag a millimeter at a time.
The third mistake is losing the EXIF orientation. An iPhone portrait photo uploads sideways, users complain, and support assumes the user took the photo wrong. The fix was covered above: rotate the pixels during client-side compression, so nothing downstream depends on EXIF again.
The fourth mistake is storing the avatar master as PNG. Lossless is nice, but avatars don't need lossless: a 512-pixel PNG easily reaches 500KB, ten times the same image as a JPEG. Store JPEG by default, and only consider PNG when a user uploads an image with a transparent background.
The fifth mistake is having no rate limit on avatar changes. Ad accounts change their avatar 20 times a day, each time to an image carrying a QR code, rotating through comment threads. A limit of 3 a day never touches normal users — but it stops ad accounts cold.
Drawing the line: an avatar is not a profile page, and cropping is not a filter
One final boundary. The site previously published a guide on profile pages (vibe-project-public-profile-page-guide), about the structure and content of a profile page; this guide covers only the avatar element, in depth rather than breadth. The avatar is one piece of the profile page puzzle, but its pitfalls — cropping, compression, EXIF, moderation — are all things the profile-page guide never covered.
It is also worth separating cropping from filters: cropping is "which part stays," a filter is "what the part that stays looks like." This guide does not cover filters, because the return on avatar filters is very low: at 96 pixels, users cannot tell the difference a filter makes, and adding filters only complicates the upload chain. If you want to build image beautification, do it for post attachments — those images are big enough for users to see the difference.
In one sentence: what a well-built avatar feature looks like
What does an avatar feature look like when it is done right? The user picks a photo, the crop frame lands on their face automatically, the circular preview shows the result at a glance, tapping confirm uploads it in three seconds, and seven days later the avatar is still there — sharp, upright, not cut in half. The whole process asks the user to think about nothing, retry nothing, and contact support about nothing. That is the standard: pick, crop, compress, display — four steps, each done right once, adding up to an avatar feature that feels like it isn't there at all.
Comments (0)
Related articles
One page should stand up on a phone, a tablet, and a computer. This guide follows MDN's Responsive web design, Using media queries, and the viewport meta reference: fluid HTML, the viewport tag, fluid grids and max-width, images that never burst their container, media query syntax, breakpoints set by content, mobile first, responsive type, testing capability instead of width, and a pre-launch checklist.
localStorage only stores strings and has no indexes. IndexedDB is a real database in the browser: structured data, far larger capacity, indexes, and transactions. Following MDN's Using IndexedDB, IDBDatabase, and IDBObjectStore: the five-step routine, opening, upgrades, keys, indexes, transactions, add versus put, get, cursors, ranges, and multi-tab upgrades.
You already call functions every day; this guide names what you have been doing. Following MDN's Functions, Arrow function expressions, and Rest parameters: declarations versus expressions, parameters and arguments, default values, rest parameters, spread syntax, return values, arrow function shorthand, the this trap, callbacks, and scope.