ShapeMask
Wrap consumer-owned media in preset or custom masks; captions and actions stay outside.
Live TypeScript example
Try the component here, then use the source below in your application.
- JavaScript
- 3.1 KiB
- Component CSS
- 0.4 KiB
- Shared theme CSS
- 3.8 KiBonce per application
How sizes are measured
The JavaScript figure includes this component’s required helpers. CSS includes its styling dependencies. Each entry is bundled separately for ES2022, minified, then compressed with gzip level 9. Your bundler may share helpers across components. Images, fonts, examples and application code are excluded.
Before compression: JavaScript 7.1 KiB; component CSS 1.1 KiB. These figures describe browser assets, not the complete package download.
View all component measurements →The mask wraps consumer-owned media. Keep captions and interactive controls outside the mask. Optional motion respects reduced-motion preferences.
import '@blukavantui/web/theme.css'
import {createShapeMask} from '@blukavantui/web/shape-mask';
import '@blukavantui/web/shape-mask.css';
export function mount(host:HTMLElement){
const stage=document.createElement('div');stage.style.maxWidth='520px';host.append(stage);
const image=document.createElement('img');image.src=import.meta.env.BASE_URL+'images/shape-mask-studio.jpg';image.alt='A glass-walled studio filled with natural light';
const caption=document.createElement('p');caption.textContent='Studio interior. Captions and controls remain outside the mask.';
const replay=document.createElement('button');replay.type='button';replay.textContent='Replay reveal';
host.append(caption,replay);let revision=0;
const mask=createShapeMask(stage,{Content:image,Shape:'Arch',AspectRatio:'4 / 3',Animation:'Reveal'}, {Error:message=>{caption.textContent=message;}});
replay.onclick=()=>mask.update({AnimationKey:String(++revision)});
// Shape:'Custom', MaskUrl:'/images/brand-mask.svg' accepts your own silhouette.
return {destroy(){mask.destroy();stage.remove();caption.remove();replay.remove();}};
}
const instance = mount(document.getElementById('example')!)
// When this page or framework component is removed:
// instance.destroy()
Install the library and add the host element
npm install https://blukavantui.blutekmedia.com/downloads/blukavantui-web-0.9.0.tgz<div id="example"></div>This example uses the downloadable @blukavantui/web package. Your application handles persistence and authentication through its typed callbacks. The starter ZIP includes this same example.
createShapeMask
Pass the actual media node as Content. Its alt text and DOM identity remain intact. Shape presets or an application-owned MaskUrl create the silhouette; put captions and interactive controls outside. MaskUrl must permit cross-origin access if hosted elsewhere. A failed custom mask leaves content visible. Reveal and Zoom are finite and automatically stop under reduced motion.
import { createShapeMask } from '@blukavantui/web/shape-mask';
import '@blukavantui/web/shape-mask.css';Load @blukavantui/web/theme.css once in your app shell.createShapeMask(host: HTMLElement, options: ShapeMaskOptions, events?: ShapeMaskEvents)Reference for @blukavantui/web 0.9.0. Required and optional follow the shipped TypeScript declarations; optional does not imply a particular default. Pass typed arrays and objects directly where shown.
Options
14| Name | Type / requirement | Usage |
|---|---|---|
Content | SlotRequired | Content slot: pass a DOM node or a text string. Strings are rendered as text. |
Shape | 'None' | 'Circle' | 'Oval' | 'Diamond' | 'Hexagon' | 'Arch' | 'Organic' | 'Custom'Optional | None, Circle, Oval, Diamond, Hexagon, Arch, Organic or Custom. |
MaskUrl | stringOptional | SVG or image alpha mask. Relative or HTTP(S), including OutSystems Resource URLs. |
AspectRatio | stringOptional | Positive width / height ratio, such as 4 / 3. |
MaskSize | numberOptional | Mask extent in percent, 10–150. |
PositionX | numberOptional | Horizontal mask center, 0–100 percent. |
PositionY | numberOptional | Vertical mask center, 0–100 percent. |
Rotation | numberOptional | Mask rotation in degrees; media stays upright. |
FlipHorizontal | booleanOptional | Mirror the mask horizontally. |
FlipVertical | booleanOptional | Mirror the mask vertically. |
Animation | 'None' | 'Reveal' | 'Zoom'Optional | None, Reveal or Zoom. Finite effect; reduced motion always overrides it. |
AnimationDuration | numberOptional | Animation duration in milliseconds, clamped to 0–2000. |
AnimationKey | stringOptional | Change to replay the finite effect. Reduced motion always overrides it. |
ExtendedClass | stringOptional | Additional wrapper classes. |
Callbacks
2| Name | Type / requirement | Usage |
|---|---|---|
Loaded | (url: string) => void | Promise<void>Optional | Reports Successfully loaded custom mask URL. |
Error | (message: string) => void | Promise<void>Optional | Reports Mask error; content remains visible without masking. |
Instance methods & properties
3| Name | Signature / type | Usage |
|---|---|---|
element | HTMLElement | Root owned by this instance. Dispose before removing its host. |
update | (patch: Partial<ShapeMaskOptions>) => void | Apply a partial options update to this instance. |
destroy | () => void | Dispose the instance and its listeners when the view is removed. |
Related data types
Expand a type for its fields and allowed values.
Callback
type Callback<T extends unknown[] = []> = (...args: T) => void | Promise<void>;CommonOptions
interface CommonOptions {
ExtendedClass?: string;
}Slot
type Slot = Node | string;Use these inputs, events, actions and structures in Service Studio. Names and data bindings are specific to the native Blocks.
Published in Community and Enterprise with live native showcase screens. Accessibility results and remaining review items are listed on the accessibility status page.
Included in the planned free BluKavantUI Community edition. The official OutSystems Forge release is coming soon. View Community scope →
@if(nativeUrl)@if(nativeUrl)Open OutSystems showcase ↗@endif@endif- Web runtime
- Supported
- TypeScript
- Supported
- OutSystems
- Supported
Statuses describe the component’s rendered code and interactions. Supply accessible content and follow the component guidance when integrating it.
Accessibility guidance → · Review evidence →Purpose and use
Wrap consumer-owned media in preset or custom masks; captions and actions stay outside.
Keyboard design guidance
Content and its reading order are preserved. Keep captions and interactive controls outside the mask. Finite animations respect reduced motion.
See the support status above for review coverage and any limitations.
In your application
Provide useful labels, preserve visible focus, and test the component with your actual content. Use text alongside status colors and check contrast in each state.
Events0No events yet.
Interact with an example to see its events.