Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Logo ring

Show a placeholder until a checked image replaces it; a remove control clears a stored logo.

Placeholder, then picked image
A placeholder ring that a checked image replaces.
Show code
<app-image-picker name="workspaceLogo" fallback="WS" overlay-label="Upload workspace logo" />
Clearable ring
A ring with a remove control.
Show code
<app-image-picker name="removableLogo" value="/img/sample-logo.png" removable="true" overlay-label="Update photo" />
A custom overlay
A ring with its own overlay label.
Show code
<app-image-picker fallback="AC" overlay-label="Change logo" overlay-icon="upload" aria-label="Change company logo" />

Crop before upload

Let the person frame the image before it uploads, with a square or free crop frame.

Square frame
A 1:1 frame, round on a circle ring.
Show code
<app-image-picker name="croppedLogo" crop="1" fallback="AC" />
Free crop
Corner handles resize the frame to any shape.
Show code
<app-image-picker name="coverImage" crop="free" shape="Rounded" fallback="AC" />

Sizes and shapes

Size takes sm, md or lg, or a pixel diameter; a logo can be circle, rounded or square.

sm, md and lg
Three rings at the presets.
Show code
<app-image-picker size="ControlSize.Sm" fallback="WS" />
<app-image-picker size="ControlSize.Md" fallback="WS" />
<app-image-picker size="ControlSize.Lg" fallback="WS" />
Exact pixel sizes
A ring at a set pixel diameter.
Show code
<app-image-picker size-px="56" fallback="WS" />
<app-image-picker size-px="96" fallback="WS" />
<app-image-picker size-px="140" fallback="WS" />
circle, rounded and square
The three shapes.
Show code
<app-image-picker shape="Circle" fallback="WS" />
<app-image-picker shape="Rounded" fallback="WS" />
<app-image-picker shape="Square" fallback="WS" />
Avatar sizes
The avatar preset at sm, md and lg: 64, 96 and 128 px.
Show code
<app-image-picker kind="Avatar" size="ControlSize.Sm" fallback="NS" />
<app-image-picker kind="Avatar" size="ControlSize.Md" fallback="NS" />
<app-image-picker kind="Avatar" size="ControlSize.Lg" fallback="NS" />

Placeholder style

Use initials for a brand's letters, or the avatar disc when the picture is of a person.

Initials and avatar
An empty ring with initials from fallback, then with the avatar disc.
Show code
<app-image-picker variant="AppImagePickerVariant.Initials" fallback="WS" />
<app-image-picker variant="AppImagePickerVariant.Avatar" fallback="WS" />

Identity layouts

Lay the ring beside a name and role, or centre it above them, with helper text under both.

Avatar, name, role and helper text
The inline row.
Ishita Jindal
Admin
Allowed *.jpeg, *.jpg, *.png
Show code
<app-image-picker layout="Inline" fallback="IJ" title="Ishita Jindal" subtitle="Admin" helper-text="Allowed *.jpeg, *.jpg, *.png" />
Centred identity card
The profile column.
Ishita Jindal
Admin
Show code
<app-image-picker layout="Profile" fallback="IJ" title="Ishita Jindal" subtitle="Admin" />

Profile photo

Use the avatar kind for a person's photo, with a round crop, a camera and a remove control.

A profile photo
The photo beside its buttons.
Show code
<app-image-picker kind="Avatar" name="profilePhoto" fallback="NS" label="Profile photo" />
In a plain form
A photo written into a file input.
Show code
<form method="post" enctype="multipart/form-data">
    <app-image-picker kind="Avatar" name="photo" fallback="NS" />
</form>
With Remove
A remove control that tells the page.
Show code
<app-image-picker kind="Avatar" value="/img/sample-logo.png" fallback="NS" remove-name="removePhoto" removable="true" />

Label and states

Label the picker like any form field, and show loading or disabled while work runs or the picker is read only.

Required picker with an error
A required labelled picker.
PNG or JPG, at least 200x200px.
Please upload a logo.
Show code
<app-image-picker label="Company logo" required="true" helper-text="PNG or JPG, at least 200x200px." fallback="AC" />
<app-image-picker label="Company logo" required="true" error="Please upload a logo." fallback="AC" />
Uploading and disabled
A loading picker and a disabled one.
Show code
<app-image-picker loading="true" fallback="WS" />
<app-image-picker disabled="true" fallback="WS" />
Avatar states
A loading avatar picker, a disabled one and one showing an error.
That photo could not be saved.
Show code
<app-image-picker kind="Avatar" fallback="NS" loading="true" />
<app-image-picker kind="Avatar" fallback="NS" disabled="true" />
<app-image-picker kind="Avatar" fallback="NS" error="That photo could not be saved." />

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"
Acme Ltd
Client
layout="profile"
Ishita Jindal
Admin

value

(default): no value, the ring shows its fallback
value="/img/sample-logo.png"

fallback

fallback="AC"
(default): no fallback, an empty ring

name

name="workspaceLogo"
(default): no name, nothing is posted

onChange

name="pickedLogo" (React: onChange), posts the file

onRemove

removable="true" (React: onRemove), shows Remove
value without removable: no Remove shown

removeName

remove-name="removePhoto": posts true when Remove is pressed

loading

(default): loading off
loading="true"

disabled

(default): disabled off
disabled="true"

title

(default): no title
title="Ishita Jindal" (inline or profile layout)
Ishita Jindal

subtitle

(default): no subtitle
Ishita Jindal
subtitle="Admin" (inline or profile layout)
Ishita Jindal
Admin

label

(default): no label
label="Company logo"

helperText

(default): no helper text
helper-text="PNG or JPG, at least 200x200px."
PNG or JPG, at least 200x200px.

error

(default): no error
error="Please upload a logo." (replaces the helper text)
Please upload a logo.

required

(default): not required
required="true" (marked on the label)

accept

(default): PNG, JPG and WebP for logo
accept="image/png" (PNG only)

maxSizeMb

(default): 5 MB for logo
max-size-mb="1"
max-size-mb="0": no size limit

crop

(default): no crop step for logo
crop="1" (square frame)
crop="free"

rotatable

(default): no rotation for logo
rotatable="true"

previews

(default): no live previews for logo
previews="true"

camera

(default): no Take photo button for logo
camera="true" (Take photo button)

outputSize

(default): 512 for avatar
output-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 photo
overlay-label="Change logo"

removeLabel

(default): Remove photo
remove-label="Remove logo"

ariaLabel

(default): Upload photo for the overlay
aria-label="Upload workspace logo"

className

(default): no extra class
input-class="demo-picker" (React: className)

fieldClassName

(default): no extra class
class="demo-field" (React: fieldClassName), the field wrapper

optional

(default): no (optional) suffix
optional (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

Do

Set an overlay label that names the thing, such as "Change logo", so the hover affordance says exactly what happens.

Avoid

A generic "Click" overlay tells the user how to interact but not what the action does.

Label and size the picker

Do
Your face, looking at the camera.

Say what a good photo is. People crop better when they know.

Avoid

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.

logo avatar
(kind default) overlay buttons
sm md lg
(none) 64 96 120
circle rounded square
(none) inline profile
(none) /img/sample-logo.png
(kind default) 1 free
(kind default) initials avatar
(kind default) 2 5 10 0
(kind default) true false
React, generated from the controls
<AppImagePicker
  onChange={onChange}
  fallback="WS"
  name="pgImage"
/>
Razor, the same props
<app-image-picker name="pgImage" fallback="WS" />

44 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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 pairs

Name the action the overlay performs

Do

Set an overlay label that names the thing, such as "Change logo", so the hover affordance says exactly what happens.

Avoid

A generic "Click" overlay tells the user how to interact but not what the action does.

Label and size the picker

Do
Your face, looking at the camera.

Say what a good photo is. People crop better when they know.

Avoid

A tiny, disabled avatar picker with no label. Nobody can tell it sets their photo.