Photo uploader¶

Usage¶

The photo uploader allows users to upload an image via file browser. It optionally provides an edit dialog for cropping the image.

When to use¶

• In the user profile so the user can choose/change his avatar.
• When a user is created.

Best practices¶

• The original image is kept (if necessary, a compressed version of it) so the user can undo the cropping.
• Display the compressed version of the image in the preview if compression is required.
• Adjust the size according to layout needs.
• The placeholder can use any of the avatar colors.

Design¶

Elements¶

The photo uploader has different states based on the upload status:

• Initial state: When no image is uploaded, a placeholder with the user's initials will be shown.
• Image uploaded: Once a image is uploaded, options to remove or change the image will be displayed.

1. Initials, 2. Upload button, 3. Image, 4. Change button, 5. Remove button

Additionally, a dialog can be enabled to allow users to crop the image if necessary.

1. Title, 2. Description, 3.Image, 4.Crop mask, 5. Change image button, 6.Cancel and Apply button

Mask shape¶

The image mask can be set to a square or rounded shape according to the layout.

Validation¶

If the user tries to upload a file that exceeds the allowed limit, the component will not upload the new image and will display an error message.

Code¶

Usage¶

The component SiPhotoUploadComponent makes use of the open source software ngx-image-cropper. You need to add the npm package to your project, before you can make use of the photo upload component.

Import the SiPhotoUploadComponent in your standalone component that shall provide a photo upload.

import { Component } from '@angular/core';
import { SiPhotoUploadComponent } from '@siemens/element-ng/photo-upload';

@Component({
  selector: 'app-sample',
  template: `<si-photo-upload />`,
  imports: [SiPhotoUploadComponent]
})
export class SampleComponent {}

Adjust size¶

Consuming applications can customize the component size via the following CSS variables:

• --si-photo-upload-photo-width (default: 200px)
• --si-photo-upload-photo-height (default: 200px)

The snippet below shows how to use the Angular component styles attribute to adjust the size to 300px x 300px:

import { Component } from '@angular/core';
import { SiPhotoUploadComponent } from '@siemens/element-ng/photo-upload';

@Component({
  selector: 'app-sample',
  template: `<si-photo-upload />`,
  imports: [SiPhotoUploadComponent],
  styles:
    'si-photo-upload { --si-photo-upload-photo-width: 300px; --si-photo-upload-photo-height: 300px; }'
})
export class SampleComponent {}

Image cropping¶

To implement custom image cropping — whether in an upload dialog, an image editor, or a photo workflow — you can use the image cropper as a standalone component.

Simply wrap the <image-cropper> element from the ngx-image-cropper library with <si-image-cropper-style>.

This ensures the component matches Element’s theming while granting you full control over its configuration and behavior.

import { Component } from '@angular/core';
import { SiImageCropperStyleComponent } from '@siemens/element-ng/photo-upload';
import { ImageCropperComponent, ImageCroppedEvent } from 'ngx-image-cropper';

@Component({
  selector: 'app-sample',
  template: `
    <si-image-cropper-style>
      <image-cropper
        format="jpeg"
        [imageURL]="imageSource"
        [maintainAspectRatio]="true"
        [aspectRatio]="1"
        (imageCropped)="onImageCropped($event)"
      />
    </si-image-cropper-style>
  `,
  imports: [ImageCropperComponent, SiImageCropperStyleComponent]
})
export class SampleComponent {
  imageSource = 'path/to/your/image.jpg'; // URL to your image

  onImageCropped(event: ImageCroppedEvent) {
    // Handle the cropped image
    const croppedImage = event.base64;
    // Use the cropped image as needed
  }
}

Security considerations¶

The sourcePhotoUrl is marked as a trusted resource URL and is not sanitized by Angular. Only pass URLs from trusted sources.

SiPhotoUploadComponent API Documentation¶

A component used to upload, edit, and delete a user's photo. The user can upload a photo either via file browser or a URL to the photo. You can set the source photo with the sourcePhoto Data URL input or the sourcePhotoUrl URL input. If you already have a cropped image you can set it with the croppedPhoto input. Cropping changes are emitted via the croppedPhotoChange output.

Input Properties¶

Output Properties¶

Types Documentation¶