---
title: Image
description: Mağaza sahibinden görsel yüklemesini isteyen Image prop tipi ve Image component'inin kullanımı.
---

<Callout type="warn" title="Eski altyapı">
Bu sayfa, ikas Studio öncesindeki headless tema altyapısını anlatır. Yeni temalar için [ikas Studio](https://builders.ikas.com/docs/ikas-studio) dokümantasyonunu kullanın.
</Callout>

Image prop tipi, tema editöründe mağaza sahibine bir görsel seçme component'i gösterir ve bir görsel yüklemesini ister. Component'inize gelen prop değeri bir [IkasImage](https://builders.ikas.com/docs/headless-theme/api/theme-and-common#ikas-image) instance'ıdır.

Bir görsel gösteren basit bir component oluşturalım.

<iframe src="https://demo.arcade.software/swdkbFlbbnYUMLmUgMEs?embed" title="Image prop tipi demosu" loading="lazy" allowFullScreen style={{ width: '100%', aspectRatio: '16 / 9', border: 0, borderRadius: 12 }} />

Bunun için [Next Image](https://nextjs.org/docs/api-reference/next/image) üzerine geliştirdiğimiz [Image](#image-component-props) component'ini kullanıyoruz.

```tsx title="src/components/image-prop/index.tsx"
import { observer } from 'mobx-react-lite';
import { Image } from '@ikas/storefront';
import { ImagePropProps } from '../__generated__/types';

import styles from './style.module.css';

const ImagePropDemo: React.FC<ImagePropProps> = (props) => {
  const { image } = props;
  return (
    <div className={styles['img-container']}>
      <Image image={image} layout="fill" sizes="500px" objectFit="contain" />
    </div>
  );
};

export default observer(ImagePropDemo);
```

```css title="src/components/image-prop/style.module.css"
.img-container {
  position: relative;
  width: 500px;
  height: 500px;
  margin: 48px auto;
}
```

## Layout tipleri [#layout-types]

Bu örnekte, kare bir görseli bir container içinde göstermek için `fill` layout tipini kullandık. Ancak görseller için çok daha fazla kullanım senaryosu ve farklı layout ihtiyacı vardır. Bu layout tipleri ve nasıl kullanılmaları gerektiği, örnek görsellerle birlikte [next/image](https://nextjs.org/docs/api-reference/next/image#layout) dokümantasyonunda anlatılır. Bu dokümana göz atmanızı ve farklı senaryoları kendiniz denemenizi öneririz. Layout tiplerini kısaca özetlemek gerekirse:

- `intrinsic`

  Container'ın genişliği görselin genişliğinden küçükse görselin container genişliğine göre küçülmesini istiyorsanız bu layout tipini kullanın. Container'ın genişliği görselden büyükse görsel container boyutuna uyacak şekilde büyümez, orijinal boyutunu korur.

- `fixed`

  Sabit boyutlu bir görsel istiyorsanız bu layout tipini kullanın. Görselin boyutunu verdiğiniz `width` ve `height` parametreleri belirler. Genellikle responsive olarak boyut değiştirmesi gerekmeyen küçük ikonlar ya da logolar için kullanılır.

- `responsive`

  Görselin, container'ının genişliğine göre küçülüp büyümesini istiyorsanız bu layout tipini kullanın. Genellikle 3 ya da 4 görselin yan yana gösterildiği grid düzenlerinde ya da solda ürün görsellerinin, sağda bilgilerin yer aldığı ürün detay component'lerinde kullanılır.

  Burada `width` ve `height` prop'larını görsele bir en-boy oranı vermek için kullanabilirsiniz.

  Örneğin prop'ları aşağıdaki gibi verirseniz görsel 16:9 en-boy oranına sahip bir alanı doldurmaya çalışır. Görselin bu 16:9 alanı kaplaması için `objectFit` prop'unu da kullandığımıza dikkat edin.

  Her cihaz boyutunda yükleme performansını iyileştirmek için [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes) attribute'unu da vermelisiniz.

  ```tsx
  <Image image={image} layout="responsive" width={16} height={9} sizes="500px" objectFit="cover" />
  ```

- `fill`

  Görselin container'ının boyutunu doldurmasını istiyorsanız bu layout tipini kullanın. Genellikle container'a sabit bir boyut verebildiğiniz ve görselin bu container'ın sınırları içinde kalmasını istediğiniz durumlarda kullanılır.

  Her cihaz boyutunda yükleme performansını iyileştirmek için [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes) attribute'unu da vermelisiniz.

[Next Image](https://nextjs.org/docs/api-reference/next/image) component'ini daha önce kullanmadıysanız bu yaklaşım başta biraz yabancı gelebilir. Ancak mevcut prop'lar ve container boyutlarıyla denemeler yaptıkça görselleri kolayca responsive şekilde gösterebilirsiniz.

## Sizes attribute'u [#sizes-attribute]

`responsive` ve `fill` layout tiplerinde, tarayıcının mevcut viewport ve cihaz piksel oranı için uygun boyutta görseli indirebilmesi amacıyla [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes) attribute'una doğru değerler vermeniz gerekir. Bu değeri vermezseniz görsel yükleme süreleri ciddi şekilde uzar ve temanız oldukça yavaş hissettirir.

`sizes` attribute'u, görselinizin farklı ekran boyutlarında ekranda gerçekte ne kadar genişlik kapladığını tarif eder. Örneğin responsive bir görseliniz var ve görselin genişliği 768px altındaki ekranlarda 120px, 1440px altındaki ekranlarda 360px, 1440px üzerindeki ekranlarda ise 540px ise `sizes` değerini şöyle yazarsınız:

```tsx
<Image
  image={image}
  layout="responsive"
  width={16}
  height={9}
  sizes="(max-width: 768px) 120px, (max-width: 1440px) 360px, 540px"
  objectFit="cover"
/>
```

Bu `sizes` değeriyle tarayıcıya şunu söylemiş olursunuz:

```
Görselimin genişliği;
  - 768px viewport genişliğinin altında 120px,
  - 768px ile 1440px viewport genişliği arasında 360px,
  - 1440px viewport genişliğinin üzerinde 540px.
```

Tarayıcınız bu değerleri ve cihazınızın piksel oranını kontrol ederek mevcut viewport için en uygun boyuttaki görseli indirir. [sizes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-sizes) özelliği hakkında daha fazla bilgiye bu linkten ulaşabilirsiniz.

"Görselimin sabit bir boyutu yok, sürekli küçülüp büyüyor; bu breakpoint'ler için nasıl sabit değerler vereceğim?" diye düşünebilirsiniz. Bu durumda, tarayıcıya görsel boyutunun belirgin şekilde büyüdüğünü ya da küçüldüğünü bildirmek için gerekli gördüğünüz kadar breakpoint ekleyin. Görsel genişliği 50px artıyorsa bunun için yeni bir breakpoint'e ihtiyacınız olmayabilir. Ancak görsel 200-300px büyüyorsa bunu tarayıcıya bildirmek daha doğru olur.

Son olarak, görselinizin boyutu viewport genişliğine orantılı olarak değişiyorsa görsel boyutunu belirtmek için `vw` birimini kullanabilirsiniz. Örneğin görseliniz viewport'un tüm genişliğini kaplıyorsa şöyle yazmanız yeterlidir:

```tsx
<Image image={image} layout="responsive" width={16} height={9} sizes="100vw" objectFit="cover" />
```

## Image component prop'ları [#image-component-props]

<TypeTable
  type={{
    image: {
      type: 'IkasImage',
      required: true,
      description: "src attribute'u yerine IkasImage nesnesi verilir. Image component'i, verilen IkasImage nesnesiyle kendi içinde bir srcset oluşturur.",
    },
    layout: {
      type: '"fill" | "fixed" | "intrinsic" | "responsive" | undefined',
      description: "Görselin nasıl render edileceğini belirleyen layout değeri. Ayrıntılar için Layout tipleri başlığına bakın.",
    },
    width: {
      type: 'number | string | undefined',
      description: 'Görselin piksel cinsinden genişliği. Birim içermeyen bir tam sayı olmalıdır. layout="fill" kullanılan görseller dışında zorunludur.',
    },
    height: {
      type: 'number | string | undefined',
      description: 'Görselin piksel cinsinden yüksekliği. Birim içermeyen bir tam sayı olmalıdır. layout="fill" kullanılan görseller dışında zorunludur.',
    },
    sizes: {
      type: 'string | undefined',
      description: "Responsive görsel boyutunu tarayıcıya tarif eden sizes değeri. Layout tipi responsive ya da fill ise verilmelidir. Ayrıntılar için Sizes attribute'u başlığına bakın.",
    },
    objectFit: {
      type: 'fill | contain | cover | none | scale-down | undefined',
      description: 'layout="fill" kullanıldığında görselin container\'ına nasıl yerleşeceğini belirler. Bu değer görselin object-fit CSS özelliğine aktarılır.',
    },
    objectPosition: {
      type: 'fill | contain | cover | none | scale-down | undefined',
      description: 'layout="fill" kullanıldığında görselin container\'ı içinde nasıl konumlanacağını belirler. Bu değer görselin object-position CSS özelliğine aktarılır.',
    },
    priority: {
      type: 'boolean | undefined',
      description: "true olduğunda görsel yüksek öncelikli kabul edilir ve önceden yüklenir (preload). priority kullanan görsellerde lazy loading otomatik olarak kapatılır. Sayfanın ilk yükleme süresini etkileyen büyük görsellerde performansı artırmak için kullanılmalıdır.",
    },
    useBlur: {
      type: 'boolean | undefined',
      description: "true yapıldığında Image component'i, alttaki NextImage component'ine bir blurDataURL verir. Böylece asıl görsel yüklenene kadar yer tutucu olarak çok küçük boyutlu, bulanık bir görsel gösterilir.",
    },
  }}
/>

`objectFit` ve `objectPosition` hakkında daha fazla bilgi için [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) ve [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position) dokümanlarına bakabilirsiniz.

<Callout type="info" title="priority kullanımı">
Örneğin görsel içeren büyük bir banner component'iniz varsa sayfa performansını artırmak için bu görsele öncelik vermek isteyebilirsiniz. Ayrıntılar için [next/image priority](https://nextjs.org/docs/api-reference/next/image#priority) dokümanına bakın. `useBlur` için de [blurDataURL](https://nextjs.org/docs/api-reference/next/image#blurdataurl) dokümanını inceleyebilirsiniz.
</Callout>

## Özet [#summary]

Temanızda göstereceğiniz her görsel için, ister doğrudan bir `Image` prop tipinden ister [IkasProductVariant](https://builders.ikas.com/docs/headless-theme/api/products#ikas-product-variant) gibi başka bir model üzerinden gelsin, her zaman bir `IkasImage` nesnesine sahip olursunuz ve bu nesneyi `@ikas/storefront` paketindeki `Image` component'iyle göstermeniz beklenir.

Görsel boyutları mağazadan mağazaya değişir: Bazı mağaza sahipleri kare görseller yüklerken bazıları dikdörtgen boyutları tercih eder. Mağaza sahiplerine en esnek görsel deneyimini sunmak için, görsellerini component'lerinize istedikleri şekilde yerleştirebilmelerini sağlayan prop'lar ekleyebilirsiniz. Bu prop'lara birkaç örnek:

- `objectFit`: Bir [enum](https://builders.ikas.com/docs/headless-theme/prop-types/custom-data#enums) tipi oluşturup mağaza sahibine görselin container'ı kaplamasını mı yoksa içine sığmasını mı istediğini sorabilirsiniz.
- `aspectRatio`: `16:9`, `4:3`, `1:1` gibi seçenekler içeren bir [enum](https://builders.ikas.com/docs/headless-theme/prop-types/custom-data#enums) tipi oluşturup component'inizdeki görselleri buna göre boyutlandırabilirsiniz.
- `mobileImage`: Mobil cihazlar için mağaza sahibinden tamamen farklı bir görsel isteyebilirsiniz.

Örnekler çoğaltılabilir. Mağaza sahiplerine en esnek ve genel çözümü sunmak, tema geliştiricisi olarak size kalmıştır.