Live Avatar
When an UploadType field completes its upload, the signed reference lands on an
#[UploadTarget] prop and the component renders again with the name and size
it received. No form submission, no page reload. The picture is the preview
of your browser: this public server keeps no file and sends none back.
No avatar yet
A prop that accepts an upload
Only a nullable string prop carrying #[UploadTarget] can receive an upload:
the attribute is the allow-list. The prop stores the same signed reference a
form field sends.
getUpload('photo') resolves it into an UploadedFile, or null.
24#[AsLiveComponent]
25final class UploadAvatar
26{
27 use ComponentWithUploadTrait {
28 getUpload as private resolveUpload;
29 }
30 use DefaultActionTrait;
31
32 #[LiveProp]
33 #[UploadTarget(uploader: 'avatars')]
34 public ?string $photo = null;
35
36 public function __construct(private readonly FormFactoryInterface $formFactory)
37 {
38 }
39
40 public function getUpload(string $property): ?UploadedFile
41 {
42 return $this->resolveUpload($property);
43 }
44
45 public function getUploadForm(): FormView
46 {
47 return $this->formFactory->create(AvatarUploadForm::class)->createView();
48 }
49}
The bridge applies it
The live-upload controller wraps the field. When the upload completes, it
reads the signed reference from the field event and calls the applyUpload
live action.
The component renders again with the name and the size it received: no form
submission, no page reload. data-live-ignore keeps the field, and the picture
the browser drew, out of that render.
The other way round, the remove event of the field calls clearUpload: taking
the file out empties the prop.
<div {{ attributes.defaults(stimulus_controller('symfony/ux-upload/live-upload', {property: 'photo'})) }} class="UploadAvatar">
{{ form_label(this.uploadForm.photo) }}
{# Shown while the field is empty: its own preview is the avatar #}
<span class="UploadAvatar_picture"><twig:ux:icon name="lucide:user" /></span>
{# The field stays out of the render: its Remove button tells the component to clear the prop #}
<div
data-live-ignore
data-action="symfony--ux-upload--upload:remove->live#action"
data-live-action-param="clearUpload"
data-live-property-param="photo"
>
{{ form_widget(this.uploadForm.photo) }}
</div>
<div class="UploadAvatar_status">
{% set upload = this.getUpload('photo') %}
{% if upload %}
<p class="UploadStage_outcome">Received by the component: <strong>{{ upload.clientOriginalName }}</strong>, {{ (upload.size / 1024)|round(1) }} KB</p>
{% else %}
<p>No avatar yet</p>
{% endif %}
</div>
</div>
The picture stays in the browser
The field is a plain UploadType. show_preview draws the picture from the
file the visitor selected. The avatar is that preview, enlarged in CSS: this
public server keeps no file and sends none back.
To keep the photo in your application, resolve the prop in your own live action and pass the upload to the service that stores it.
26$builder
27 ->add('photo', UploadType::class, [
28 'uploader' => 'avatars',
29 // The picture comes from the browser: the server sends no file back
30 'show_preview' => true,
31 ])
32;