On this page
@addTagHelper *, Webority.Ui.RazorLogo ring
Show a placeholder until a checked image replaces it; a remove control clears a stored logo.
Crop before upload
Let the person frame the image before it uploads, with a square or free crop frame.
Sizes and shapes
Size takes sm, md or lg, or a pixel diameter; a logo can be circle, rounded or square.
Placeholder style
Use initials for a brand's letters, or the avatar disc when the picture is of a person.
Identity layouts
Lay the ring beside a name and role, or centre it above them, with helper text under both.
Profile photo
Use the avatar kind for a person's photo, with a round crop, a camera and a remove control.
Label and states
Label the picker like any form field, and show loading or disabled while work runs or the picker is read only.
Every option
Every value of every prop, one cell each.
kind
kind="logo" (default)kind="avatar"controls
controls="overlay" (default for logo)controls="buttons" (default for avatar)variant
variant="initials" (default)variant="avatar" (no fallback: person icon)size
size="sm"size="md" (default)size="lg"size="96" (pixels)shape
shape="circle" (default)shape="rounded"shape="square"layout
layout="stacked" (default)layout="inline"layout="profile"value
(default): no value, the ring shows its fallbackvalue="/img/sample-logo.png"fallback
fallback="AC"(default): no fallback, an empty ringname
name="workspaceLogo"(default): no name, nothing is postedonChange
name="pickedLogo" (React: onChange), posts the fileonRemove
removable="true" (React: onRemove), shows Removevalue without removable: no Remove shownremoveName
remove-name="removePhoto": posts true when Remove is pressedloading
(default): loading offloading="true"disabled
(default): disabled offdisabled="true"title
(default): no titletitle="Ishita Jindal" (inline or profile layout)subtitle
(default): no subtitlesubtitle="Admin" (inline or profile layout)label
(default): no labellabel="Company logo"helperText
(default): no helper texthelper-text="PNG or JPG, at least 200x200px."error
(default): no errorerror="Please upload a logo." (replaces the helper text)required
(default): not requiredrequired="true" (marked on the label)accept
(default): PNG, JPG and WebP for logoaccept="image/png" (PNG only)maxSizeMb
(default): 5 MB for logomax-size-mb="1"max-size-mb="0": no size limitcrop
(default): no crop step for logocrop="1" (square frame)crop="free"rotatable
(default): no rotation for logorotatable="true"previews
(default): no live previews for logopreviews="true"camera
(default): no Take photo button for logocamera="true" (Take photo button)outputSize
(default): 512 for avataroutput-size="256"outputType
output-type="keep" (default for logo)output-type="image/webp"overlayIcon
overlay-icon="image" (default)overlay-icon="camera"overlay-icon="upload"overlayLabel
(default): Update photooverlay-label="Change logo"removeLabel
(default): Remove photoremove-label="Remove logo"ariaLabel
(default): Upload photo for the overlayaria-label="Upload workspace logo"className
(default): no extra classinput-class="demo-picker" (React: className)fieldClassName
(default): no extra classclass="demo-field" (React: fieldClassName), the field wrapperoptional
(default): no (optional) suffixoptional (ends the label with (optional))optionalLabel
(default): optional-label="(optional)"optional-label="(opcional)"dialogTitle
(default): dialog-title="Crop photo"dialog-title="Crop logo"dialogSubtitle
(default): dialog-subtitle="Drag the frame and zoom to choose what to keep."dialog-subtitle="Drag the frame to choose the logo."save
(default): save="Apply"save="Use this logo"cancel
(default): cancel="Cancel"cancel="Discard"cropFailed
(default): crop-failed="That image could not be cropped. Choose another one."crop-failed="That logo could not be cropped."unreadable
(default): unreadable="That image could not be opened. Choose another one."unreadable="That file could not be opened."uploadLabel
(default): upload-label="Upload photo"upload-label="Add logo"changeLabel
(default): change-label="Change photo"change-label="Replace logo"cameraLabel
(default): camera-label="Take photo"camera-label="Use camera"style
style attribute (React: style prop)Guidance
What to do, and what to avoid.
Use it when
- An identity image is being set, such as a workspace logo, a company avatar or a profile picture.
- A person sets their own profile photo, or an admin sets a staff member's photo on their record.
- You want a hover-to-change overlay plus a loading state while the file uploads.
Reach for something else when
- A single, rectangular image where the preview should be large. → AppFilePicker
- A file attached to a record where the name or size matters. → AppFileAttachment
- You only need to display an avatar, not upload one. → AppAvatar
Name the action the overlay performs
Set an overlay label that names the thing, such as "Change logo", so the hover affordance says exactly what happens.
A generic "Click" overlay tells the user how to interact but not what the action does.
Label and size the picker
Say what a good photo is. People crop better when they know.
A tiny, disabled avatar picker with no label. Nobody can tell it sets their photo.
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
44 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| kinddefault logo | Logo | Avatar | logo | The preset: logo is an identity ring, avatar is a person's profile photo. Each prop below overrides the preset. |
| namedefault - | string | - | The form field name. The chosen file, or the crop when cropping, is written into the file input, so an uncontrolled form posts it. |
| valuedefault - | string | - | The current image URL. Absent or empty means no image. |
| fallbackdefault - | string | - | Text shown when there is no image, such as initials. |
| shapedefault circle | Circle | Rounded | Square | circle | The ring or frame shape. |
Less common 39 props
| Prop | Type | Default | Description |
|---|---|---|---|
| controlsdefault from kind | Overlay | Buttons | from kind | overlay is a ring with a hover label and an x to remove. buttons is the photo beside Upload or Change, Take photo and Remove. Default overlay for logo, buttons for avatar. |
| variantdefault initials | Initials | Avatar | initials | With no fallback, avatar draws a person icon. The avatar kind uses avatar. |
| removabledefault false | bool | false | Shows the remove control while there is an image. |
| remove-namedefault - | string | - | A form field that posts true once Remove is pressed. |
| acceptdefault from kind | string | from kind | The file types a person may choose. Defaults to PNG, JPG and WebP for logo; JPG, PNG, WebP and HEIC for avatar. HEIC opens only where the browser can decode it. |
| max-size-mbdefault 5, or 10 for avatar | int | 5, or 10 for avatar | The size limit in megabytes; 0 means no limit. Defaults to 5 for logo and 10 for avatar. |
| sizedefault md | Sm | Md | Lg | md | A preset diameter (logo 72, 120, 160 px; avatar 64, 96, 128 px). |
| size-pxdefault - | number | - | The size in pixels, instead of a preset. |
| cropdefault none, or 1 for avatar | free | number | none, or 1 for avatar | Adds a crop step before upload. A number is the frame's width divided by its height, such as 1 for a round avatar; free lets the person resize the frame. Default none for logo, 1 for avatar. |
| output-sizedefault 512 for avatar | int | 512 for avatar | The width and height of the saved square, in pixels, with a crop of 1. Default none for logo, 512 for avatar. |
| output-typedefault keep, or image/webp for avatar | Keep | ImageWebp | keep, or image/webp for avatar | The type of the saved crop: keep the chosen type, or WebP. Default keep for logo, WebP for avatar. |
| cameradefault true for avatar with buttons | bool | true for avatar with buttons | Shows the Take photo button, which opens the front camera. Default false for logo, true for avatar. |
| rotatabledefault true for avatar | bool | true for avatar | Offers rotation in the crop dialog. Default false for logo, true for avatar. |
| previewsdefault true for avatar | bool | true for avatar | Shows the 96 and 48 px live previews in the crop dialog. Default false for logo, true for avatar. |
| layoutdefault stacked | Stacked | Inline | Profile | stacked | Stacked is the ring with the helper text below. Inline puts the ring on the left with a title, subtitle and helper text column beside it. Profile stacks the same identity block, centred, beneath the ring. Applies to the overlay controls. |
| titledefault - | string | - | Bold primary text, inline and profile layouts only. |
| subtitledefault - | string | - | Muted secondary text, inline and profile layouts only. |
| overlay-icondefault image | string | image | The icon name for the hover overlay. Overlay controls only. |
| overlay-labeldefault Update photo | string | Update photo | The text of the hover overlay. Overlay controls only. |
| remove-labeldefault Remove photo | string | Remove photo | The accessible name and tooltip of the remove control. Use Remove logo on a logo picker. |
| aria-labeldefault Upload photo | string | Upload photo | The accessible name of the upload control. Defaults to Upload photo for the overlay and to the action's words for buttons. |
| input-classdefault - | string | - | Extra classes on the picker itself. A plain class lands on the wrapper. |
| labeldefault - | string | - | Visible label above the picker. |
| helper-textdefault - | string | - | Helper text under the picker. An error replaces it. |
| errordefault - | string | - | An error from the caller. It wins over a rejection reason. |
| requireddefault false | bool | false | Marks the field as required. |
| optional-labeldefault (optional) | string | (optional) | Replaces the built-in English text, for other languages. |
| upload-labeldefault Upload photo | string | Upload photo | The Upload button's text on the buttons controls, when no photo is set. Replaces the built-in English text. |
| change-labeldefault Change photo | string | Change photo | The Change button's text on the buttons controls, when a photo is set. Replaces the built-in English text. |
| camera-labeldefault Take photo | string | Take photo | The Take photo button's text on the buttons controls. Replaces the built-in English text. |
| dialog-titledefault Crop photo | string | Crop photo | Replaces the built-in English text, for other languages. Default Edit photo for avatar. |
| dialog-subtitledefault Drag the frame and zoom to choose what to keep. | string | Drag the frame and zoom to choose what to keep. | Replaces the built-in English text, for other languages. Default Drag to position the photo, then zoom or rotate it. for avatar. |
| savedefault Apply | string | Apply | Replaces the built-in English text, for other languages. Default Save photo for avatar. |
| canceldefault Cancel | string | Cancel | Replaces the built-in English text, for other languages. |
| crop-faileddefault That image could not be cropped. Choose another one. | string | That image could not be cropped. Choose another one. | Replaces the built-in English text, for other languages. Default That photo could not be saved. Try again, or choose another one. for avatar. |
| unreadabledefault That image could not be opened. Choose another one. | string | That image could not be opened. Choose another one. | Replaces the built-in English text, for other languages. {name} is the file name. Avatar keeps its HEIC message when the file is HEIC. |
| optionaldefault false | bool | false | Ends the label with (optional) when the field is not required. Required wins when both are set. |
| loadingdefault false | bool | false | Shows a spinner and blocks every action while the picked file uploads. |
| disableddefault false | bool | false | Blocks every action. |
Screen reader
4 notes- The upload control is named by ariaLabel, else by Upload photo for the overlay and by the action's words (Choose or Change photo) for buttons. It is disabled and marked busy while loading.
- The remove control is its own button named by removeLabel, and it stays hidden until there is an image to remove.
- The helper text or the error is tied to the upload control with aria-describedby, and an error wins over helper text.
- The buttons look sits out of the tab order and the Upload button beside it is the keyboard path to the same action.
Do and avoid
2 pairsName the action the overlay performs
Set an overlay label that names the thing, such as "Change logo", so the hover affordance says exactly what happens.
A generic "Click" overlay tells the user how to interact but not what the action does.
Label and size the picker
Say what a good photo is. People crop better when they know.
A tiny, disabled avatar picker with no label. Nobody can tell it sets their photo.