{ "category": "Lookup and reference functions", "display_name": "IMAGE", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.IMAGE", "implementation_state": { "answer_bank": null, "detail": "No catalogue row at this commit. IMAGE fetches from the URL in the workbook, not from a Microsoft back end, and is being implemented as an ordinary function.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": false, "state": "refuses", "state_label": "Refuses or not implemented", "summary": "Not yet implemented", "workbook_corpus": null }, "implementations": [], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.IMAGE.json", "name": "IMAGE", "notes": [], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n### Relationships\n\n\n- **`WEBSERVICE`** — the older formula-initiated fetch. Both reach the network from a cell;\n `IMAGE` is narrower by design (HTTPS only, no redirects, no authentication) and returns a\n rich value rather than text.\n- **`HYPERLINK`** — returns text plus a presentation hint, and is the classic example of a\n function whose result is core-valued but display-affected. `IMAGE` goes a step further: its\n result is genuinely rich.\n- **Linked data types (Stocks, Geography) and `STOCKHISTORY`** — the other modern\n provider-backed surfaces. Linked data types share `IMAGE`'s rich-value machinery;\n `STOCKHISTORY` shares its provider dependence but returns an ordinary spilled array.\n- **Pasted pictures and \"Place in Cell\" images** — the user-interface features that produce the\n same kind of in-cell image without a formula. Readers confuse the two constantly; the\n difference is that only the formula form recalculates.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n- Argument validation is unusually strict and cross-argument. `sizing` and `height`/`width` are\n validated against each other in both directions, which means validation cannot be done\n per-argument.\n- The 255-character inline URL limit is an Excel behaviour, not a URL standard, and must be\n enforced as such.\n- The security posture — HTTPS only, no redirect following, no authenticated fetches — is part\n of the function's contract, not an environmental accident. An implementation that follows\n redirects is more permissive than the documented function.\n- `NonVolatile` plus `ExternalEventDependent` is an interesting pair: the function is not\n re-evaluated on every calculation, yet its rendered result depends on a remote resource that\n can change or vanish. Cache and refresh policy is host behaviour and is not specified by the\n function.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nA rich value that the host renders in place. The edges worth naming:\n\n- **It is a cell value, not a floating object.** Unlike a pasted picture, an `IMAGE` result\n moves, sorts and filters with its row. That is the entire reason the function exists.\n- **The image is fetched, not embedded.** The workbook holds a reference. A workbook that\n displays correctly on the author's machine may show nothing on a machine without network\n access to the host, and archival copies are not self-contained.\n- **`alt_text` is part of the value.** Changing it changes the value, not merely a display\n attribute.\n\n\n\n### Errors\n\n\nAs documented by Microsoft, `#VALUE!` covers a notably wide set of distinct causes:\n\n- the image format is unsupported;\n- `source` or `alt_text` is not a string;\n- `sizing` is not between 0 and 3;\n- `sizing` is 3 but `height` and `width` are missing or invalid;\n- `sizing` is 0, 1 or 2 but `width` or `height` was supplied anyway.\n\nTwo further codes are documented, and they are the two *extended*-family codes that the\nvalue-universe chapter lists for precisely this situation:\n\n- **`#CONNECT!`** — an internet-connection or server problem.\n- **`#BLOCKED!`** — security settings are blocking access.\n\n`IMAGE` is therefore one of the clearest published cases of the extended error family being\nreachable from an ordinary worksheet formula, and a useful anchor for anyone trying to\nunderstand what `#CONNECT!` and `#BLOCKED!` are for.\n\n\n", "sources": "- Microsoft, \"IMAGE function\" —\n \n (syntax, all five arguments, the four-value `sizing` table, the supported image formats and\n the WEBP platform exception, the HTTPS requirement, the no-authentication and no-redirect\n rules, the 255-character URL limit and its cell-reference workaround, and every `#VALUE!`,\n `#CONNECT!` and `#BLOCKED!` condition listed above).\n- Handbook `data/presence/FUNC.IMAGE.json` — the implementing module\n `earlier-implementation/image_fn.rs` and its surface-dispatch entry.\n\n\n", "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.", "what-it-does": "\n`IMAGE` is the function that broke the assumption that a formula returns a scalar. It does not\nreturn a picture *file*, a URL, or text: it returns a **rich value** that the host renders in\nthe cell, and that can be sorted, filtered, referenced and copied like any other cell value.\n\nThe retrieval itself is not the function's semantics. Microsoft's constraints make that clear\nand are worth reading as a policy specification rather than as trivia:\n\n- **HTTPS only.** The `source` must use `https`.\n- **Supported formats:** BMP, JPG/JPEG, GIF, TIFF, PNG, ICO and WEBP, with WEBP unsupported on\n Web and Android.\n- **No authentication.** Images requiring authentication will not render.\n- **No redirects.** Redirected URLs are blocked, explicitly for security reasons.\n\nThat last pair is the design statement: `IMAGE` will only fetch something a plain anonymous GET\nto a fixed HTTPS URL returns. It is deliberately not a general web fetcher, and the contrast\nwith `WEBSERVICE` — which allows redirects and returns arbitrary text — is instructive about\nhow Microsoft's posture on formula-initiated network access changed between the two functions.\n\n\n\n### Arguments\n\n\n`IMAGE(source, [alt_text], [sizing], [height], [width])` — arity 1 to 5, matching the reference\nengine's recorded arity.\n\n- **`source`** (required) — the HTTPS URL of the image file. Microsoft notes a **255-character\n limit** on the URL as written in the formula, with the documented workaround of referencing a\n cell that contains the longer URL. This is the same inline-versus-referenced asymmetry the\n cube functions carry, and it catches generated workbooks the same way.\n- **`alt_text`** (optional) — alternative text describing the image for accessibility. It is a\n real payload field, not a comment: it is what a screen reader announces.\n- **`sizing`** (optional) — one of four modes:\n\n | Value | Behaviour |\n |---|---|\n | 0 | fit the image in the cell, preserving aspect ratio |\n | 1 | fill the cell, ignoring aspect ratio |\n | 2 | keep the original image size, which may exceed the cell |\n | 3 | use the custom `height` and `width` arguments |\n\n- **`height`** (optional) — custom height in pixels; used only when `sizing` is 3.\n- **`width`** (optional) — custom width in pixels; used only when `sizing` is 3. If only one of\n the two is supplied, the aspect ratio is preserved.\n\nThe argument interaction that trips people up is **`sizing` versus `height`/`width`**, and it\nis stricter than it looks. Supplying `height` or `width` with `sizing` 0, 1 or 2 is documented\nas a `#VALUE!` error — not an ignored argument. Excel does not usually behave this way; unused\noptional arguments are more often tolerated. Here the combination is validated, in both\ndirections: `sizing` 3 without valid `height` and `width` is likewise `#VALUE!`.\n\n\n" }, "signature": { "display": "IMAGE(source, [alt_text], [sizing], [height], [width])", "parameters": [ { "description": null, "name": "source", "optional": false, "repeats": false }, { "description": null, "name": "alt_text", "optional": true, "repeats": false }, { "description": null, "name": "sizing", "optional": true, "repeats": false }, { "description": null, "name": "height", "optional": true, "repeats": false }, { "description": null, "name": "width", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "not_implemented", "reason": "No catalogue row at this commit. IMAGE fetches from the URL in the workbook, not from a Microsoft back end, and is being implemented as an ordinary function." }, "arity": { "max": 5, "min": 1 }, "category": "Lookup and reference functions", "classification": { "arg_preparation_profile": "ValuesOnlyPreAdapter", "coercion_lift_profile": "Custom", "determinism_class": "ExternalEventDependent", "error_collapse_profile": "None", "fec_dependency_profile": "ExternalProvider", "host_interaction_class": "ExternalProvider", "kernel_signature_class": "Custom", "rich_value_usage": "ProducesRichObject", "surface_fec_dependency_profile": "ExternalProvider", "thread_safety_class": "HostSerialized", "volatility_class": "NonVolatile" }, "descriptions": { "long": "The first widened tranche uses IMAGE as the rich-value publication representative rather than an ordinary scalar-return function.", "short": "A picture from a web address shown inside the cell", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns an image from a given source", "microsoft_url": "https://support.microsoft.com/en-us/office/image-function-7e112975-5e52-4f2a-b9da-1d913d51f5d5" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "IMAGE" }, { "locale": "bg-BG", "name": "IMAGE" }, { "locale": "cs-CZ", "name": "OBRÁZEK" }, { "locale": "da-DK", "name": "BILLEDE" }, { "locale": "de-DE", "name": "IMAGE" }, { "locale": "el-GR", "name": "IMAGE" }, { "locale": "en-AU", "name": "IMAGE" }, { "locale": "en-GB", "name": "IMAGE" }, { "locale": "en-US", "name": "IMAGE" }, { "locale": "es-ES", "name": "IMAGEN" }, { "locale": "et-EE", "name": "IMAGE" }, { "locale": "fi-FI", "name": "KUVA" }, { "locale": "fr-FR", "name": "IMAGE*" }, { "locale": "he-IL", "name": "IMAGE" }, { "locale": "hr-HR", "name": "IMAGE" }, { "locale": "hu-HU", "name": "KÉP" }, { "locale": "id-ID", "name": "IMAGE" }, { "locale": "it-IT", "name": "IMAGE" }, { "locale": "ja-JP", "name": "IMAGE" }, { "locale": "ko-KR", "name": "IMAGE" }, { "locale": "lt-LT", "name": "IMAGE" }, { "locale": "lv-LV", "name": "IMAGE" }, { "locale": "nb-NO", "name": "BILDE" }, { "locale": "nl-NL", "name": "Afbeelding" }, { "locale": "pl-PL", "name": "OBRAZ" }, { "locale": "pt-BR", "name": "IMAGEM" }, { "locale": "pt-PT", "name": "IMAGEM" }, { "locale": "ro-RO", "name": "IMAGE" }, { "locale": "ru-RU", "name": "ИЗОБРАЖЕНИЕ" }, { "locale": "sk-SK", "name": "IMAGE" }, { "locale": "sl-SI", "name": "IMAGE" }, { "locale": "sr-Latn-RS", "name": "SLIKA" }, { "locale": "sv-SE", "name": "BILD" }, { "locale": "th-TH", "name": "IMAGE" }, { "locale": "tr-TR", "name": "RESİM" }, { "locale": "uk-UA", "name": "IMAGE" }, { "locale": "vi-VN", "name": "IMAGE" }, { "locale": "zh-CN", "name": "IMAGE" }, { "locale": "zh-HK", "name": "IMAGE" }, { "locale": "zh-TW", "name": "IMAGE" } ], "signature": { "display": "IMAGE(source, [alt_text], [sizing], [height], [width])", "parameters": [ { "description": null, "name": "source", "optional": false, "repeats": false }, { "description": null, "name": "alt_text", "optional": true, "repeats": false }, { "description": null, "name": "sizing", "optional": true, "repeats": false }, { "description": null, "name": "height", "optional": true, "repeats": false }, { "description": null, "name": "width", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "IMAGE", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/image-function-7e112975-5e52-4f2a-b9da-1d913d51f5d5" }, "try_it": { "formula": "=IMAGE(\"https://example.com/image.png\",\"Example image\")", "note": "This example needs an Excel service or external provider that OneCalc cannot supply in this preview.", "preview_status": "refused" }, "url": "https://handbook.dnacalc.com/functions/IMAGE.html", "variants": [], "versions": [] }