StartFoundationsComponentsContent
Overview
Button Icon button Split button Button group Toggle button Toggle button group
Badge Banner Empty state Progress bar Progress ring Section message Skeleton Spinner Toast
Field Input Textarea Number input Number stepper Search field OTP input Phone input Checkbox Radio group Switch Slider Selection card Inline edit
Select family Select Combobox Multiselect Country select Date picker Date range picker Time picker Calendar Emoji picker
Dialog Sheet Popover Menu Tooltip
Sidebar Navigation menu Tab bar Segmented control Breadcrumb Pagination Tree
Table Data table Avatar Avatar group Tag Icon Image
Text Prose Link Code block Kbd
Accordion Collapsible Divider Scroll area Splitter Aspect ratio
Page header

Image

Image shows a picture with a loading placeholder, an error fallback, and lazy loading, and keeps its alt right in every state.

Stable Figma
OverviewUsageAPIAccessibility 
<tk-aspect-ratio ratio="4/3">
  <tk-image src="/photos/market.jpg" alt="A market stall of fresh fruit"></tk-image>
</tk-aspect-ratio>

Anatomy

Part What it is
tk-image the box; the image fills it
image the native <img>, fit to the box by fit
placeholder shown while the image loads; a Skeleton by default
fallback shown when the image fails or src is empty; a sunken box with an image glyph

States

<tk-aspect-ratio ratio="4/3" style="max-width: 240px">
  <tk-image alt="Product photo"></tk-image>
</tk-aspect-ratio>
State When What shows
loading src is set and not loaded yet the placeholder
loaded the image has loaded the image
error the image failed, or src is empty the fallback
  • An image already in the cache never gets stuck loading.
  • An empty src shows the fallback at once.
  • Changing src loads again, also after a failure.

Reserving space

An image without a reserved height makes the page jump when it loads. Reserve space for any image above the fold or in a list:

<tk-aspect-ratio ratio="16/9">
  <tk-image src="/photos/hero.jpg" alt="The team at the spring offsite" loading="eager"></tk-image>
</tk-aspect-ratio>
<tk-image src="/photos/chart.png" alt="Sales by month, rising since March" width="800" height="450"></tk-image>
  • Wrap it in an Aspect ratio, or
  • set width and height to the source's pixel size. They reserve the box before the image loads. They are the source size, not a ratio.

Without either, the image takes its natural ratio when it loads, and the page shifts.

Fit

  • cover (default): fills the box and crops what overflows. Use it in an Aspect ratio.
  • contain: shows the whole image and leaves empty bands.

--tk-image-position sets the focal point (default center). --tk-image-radius rounds the corners (default square).

<tk-aspect-ratio ratio="1/1" style="max-width: 160px">
  <tk-image alt="Store logo" fit="contain" style="--tk-image-radius: var(--radius-12)"></tk-image>
</tk-aspect-ratio>

Lazy loading

loading="lazy" (default) fetches the image when it nears the viewport. Use eager for the main image at the top of a page.

Lazy loading only works with reserved space. Images without a height collapse to the top of the page, and the browser fetches them all at once.