pixelpusher

Framework-agnostic <pixel-pusher> web component for image selection, optional aspect-ratio cropping, optional filters (interactive or declarative), and export with resize and quality. You can pick a file by click or drag-and-drop onto the trigger, or drive the same pipeline with selectFile(file) and selectURL(url). Use headless when you do not want the built-in upload preview UI. Install from npm, or embed the bundled build from a CDN with no build step (see below).

Install

npm install @flybits/pixelpusher
import '@flybits/pixelpusher'
// or all-in-one:
import '@flybits/pixelpusher/bundle'

CDN (embed without npm)

Load the same bundle as @flybits/pixelpusher/bundle with an ES module script (do not load both this and the default entry on one page). 

<script type="module" src="https://cdn.jsdelivr.net/npm/@flybits/pixelpusher@1.0.0-rc.1/dist/pixel-pusher.bundle.js"></script>
<pixel-pusher aspect-ratio="1" max-width="1024" max-height="1024"></pixel-pusher>

Programmatic selectFile / selectURL and the headless attribute are documented under “Programmatic selection” in the package README.

Default UI + crop

Built-in upload control; crop modal uses 16:9 and export caps. Drag an image onto the drop zone or click to pick. Events appear in the panel. 


        

      


      

        
Slotted preview (data-pp-preview)

        

          Light DOM replaces the default slot; after crop, the thumbnail updates from the
          component. While dragging files over the trigger, the element exposes
          trigger-drag-over (valid image) or trigger-drag-over-invalid
          (non-image or empty)—this demo tints the preview green or red via those attributes.
        

        

          

            
              
            
          

          

        

      


      

        
Interactive filters

        

          With interactive-filters, after crop the Edit image modal
          opens so the user can tune blur, rotation, brightness, contrast, and grayscale before
          export. filter-modal-title sets the modal title.
        

        

          

            
          

          

        

      


      

        
Declarative filters (no modal)

        

          Set filter attributes on the element for a fixed recipe—effects apply automatically after
          crop with no Edit image UI. This example rotates 90°, applies grayscale, and uses neutral
          brightness and contrast.
        

        

          

            
          

          

        

      


      

        
Export quality (WebP when set)

        

          quality controls compression on export. For non-JPEG inputs, setting
          quality typically saves the result as WebP; JPEG inputs stay JPEG. This
          instance uses quality="0.85" after crop.
        

        

          

            
          

          

        

      


      

        
No crop (pick only)

        

          aspect-ratio="0" skips the crop step. file-selected still
          fires; when processing completes, image-edited fires with the loaded image
          (resize/quality apply when set).
        

        

          

            
          

          

        

      


      

        
Programmatic API + headless

        

          With headless, the default upload preview slot is not shown; your app supplies
          controls and calls selectFile or selectURL on the element. This
          instance uses aspect-ratio="0" so there is no crop modal (one click). With
          aspect-ratio greater than zero, the same methods run the crop step as usual.
          Load sample uses a same-origin image URL from this dev build; other URLs
          must allow CORS in the browser.