{
  "_copyright": "Copyright (c) 2026, Salesforce, Inc., All rights reserved. For full license text, see the LICENSE.txt file",
  "$schema": "https://slds.lightningdesignsystem.com/schemas/uif-system.v1.json",
  "apiVersion": "1.0.0",
  "name": "File",
  "description": "Self-contained attachment unit that pairs a cropped image or doctype icon preview with an optional title bar showing the file name, type icon, and action menu.",
  "extensions": {
    "com.salesforce-ux": {
      "genReady": false
    }
  },
  "cssSource": "./file.css",
  "styleApi": {
    "status": "stable",
    "ready": true
  },
  "structure": {
    "name": "file",
    "restrict": [
      "div"
    ],
    "description": "Root file container that wraps the preview figure, optional title bar, external icon, and actions menu.",
    "attributes": {
      "static": {
        "class": "slds-file"
      }
    },
    "modifiers": [
      {
        "name": "card",
        "attribute": "class",
        "value": "slds-file_card",
        "description": "Applies the card treatment with surface container background, border, and rounded corners."
      },
      {
        "name": "overlay",
        "attribute": "class",
        "value": "slds-file_overlay",
        "description": "Adds a dark scrim overlay across the file for text-on-image legibility."
      },
      {
        "name": "loading",
        "attribute": "class",
        "value": "slds-file_loading",
        "description": "Suppresses hover preview affordances while the file is in a loading state."
      },
      {
        "name": "centerIcon",
        "attribute": "class",
        "value": "slds-file_center-icon",
        "description": "Vertically centers the doctype icon when there is no title bar."
      },
      {
        "name": "hasTitle",
        "attribute": "class",
        "value": "slds-has-title",
        "description": "Signals that a title bar is present so the hover preview icon offsets to account for it."
      }
    ],
    "children": [
      {
        "name": "figure",
        "restrict": [
          "figure"
        ],
        "description": "Figure wrapper that groups the preview crop with its caption.",
        "children": [
          {
            "name": "crop",
            "restrict": [
              "a",
              "figure"
            ],
            "description": "Crop region that constrains the preview image or doctype icon to a fixed aspect ratio.",
            "attributes": {
              "static": {
                "class": "slds-file__crop"
              }
            },
            "variants": [
              {
                "name": "ratio",
                "description": "Mutually exclusive aspect ratio applied to the crop region.",
                "options": [
                  {
                    "value": "16-by-9",
                    "class": "slds-file__crop_16-by-9",
                    "description": "Crop to a 16:9 ratio."
                  },
                  {
                    "value": "4-by-3",
                    "class": "slds-file__crop_4-by-3",
                    "description": "Crop to a 4:3 ratio."
                  },
                  {
                    "value": "1-by-1",
                    "class": "slds-file__crop_1-by-1",
                    "description": "Crop to a 1:1 ratio."
                  }
                ]
              }
            ],
            "children": [
              {
                "name": "previewAssistiveText",
                "restrict": [
                  "span"
                ],
                "description": "Visually hidden label announcing the preview action.",
                "attributes": {
                  "static": {
                    "class": "slds-assistive-text"
                  }
                }
              },
              {
                "name": "image",
                "restrict": [
                  "img"
                ],
                "description": "Preview image rendered inside the crop.",
                "renderWhen": "propFilled"
              },
              {
                "name": "icon",
                "restrict": [
                  "span"
                ],
                "description": "Doctype icon shown inside the crop when no preview image is available.",
                "renderWhen": "propFilled",
                "attributes": {
                  "static": {
                    "class": "slds-file__icon slds-icon_container"
                  }
                },
                "children": [
                  {
                    "name": "iconSvg",
                    "restrict": [
                      "svg"
                    ],
                    "description": "SVG glyph for the doctype icon.",
                    "attributes": {
                      "static": {
                        "class": "slds-icon"
                      }
                    }
                  },
                  {
                    "name": "iconAssistiveText",
                    "restrict": [
                      "span"
                    ],
                    "description": "Visually hidden label describing the doctype icon.",
                    "attributes": {
                      "static": {
                        "class": "slds-assistive-text"
                      }
                    }
                  }
                ]
              },
              {
                "name": "spinner",
                "restrict": [
                  "div"
                ],
                "description": "Loading spinner rendered inside the crop while the file is loading.",
                "renderWhen": {
                  "prop": "loading",
                  "eq": "true"
                },
                "attributes": {
                  "static": {
                    "class": "slds-spinner slds-spinner_medium"
                  }
                },
                "children": [
                  {
                    "name": "spinnerAssistiveText",
                    "restrict": [
                      "span"
                    ],
                    "description": "Visually hidden loading label.",
                    "attributes": {
                      "static": {
                        "class": "slds-assistive-text"
                      }
                    }
                  },
                  {
                    "name": "spinnerDotA",
                    "restrict": [
                      "div"
                    ],
                    "description": "First animated dot of the spinner.",
                    "attributes": {
                      "static": {
                        "class": "slds-spinner__dot-a"
                      }
                    }
                  },
                  {
                    "name": "spinnerDotB",
                    "restrict": [
                      "div"
                    ],
                    "description": "Second animated dot of the spinner.",
                    "attributes": {
                      "static": {
                        "class": "slds-spinner__dot-b"
                      }
                    }
                  }
                ]
              }
            ]
          },
          {
            "name": "title",
            "restrict": [
              "figcaption",
              "div"
            ],
            "description": "Title bar with the file name, doctype icon, and optional actions.",
            "attributes": {
              "static": {
                "class": "slds-file__title"
              }
            },
            "modifiers": [
              {
                "name": "hasActions",
                "attribute": "class",
                "value": "slds-file-has-actions",
                "description": "Reserves trailing space for the actions menu so the title can truncate cleanly."
              }
            ],
            "variants": [
              {
                "name": "treatment",
                "description": "Mutually exclusive title bar treatment.",
                "options": [
                  {
                    "value": "card",
                    "class": "slds-file__title_card",
                    "description": "Solid card title bar anchored to the bottom of the file."
                  },
                  {
                    "value": "overlay",
                    "class": "slds-file__title_overlay",
                    "description": "Full-bleed overlay title bar layered on top of the preview."
                  },
                  {
                    "value": "scrim",
                    "class": "slds-file__title_scrim",
                    "description": "Gradient scrim title bar anchored to the bottom of the file."
                  }
                ]
              }
            ],
            "children": [
              {
                "name": "media",
                "restrict": [
                  "div"
                ],
                "description": "Media object that pairs the doctype icon with the file name.",
                "attributes": {
                  "static": {
                    "class": "slds-media slds-media_small slds-media_center"
                  }
                },
                "children": [
                  {
                    "name": "mediaFigure",
                    "restrict": [
                      "div"
                    ],
                    "description": "Leading slot of the media object containing the doctype icon.",
                    "attributes": {
                      "static": {
                        "class": "slds-media__figure slds-line-height_reset"
                      }
                    },
                    "children": [
                      {
                        "name": "titleIcon",
                        "restrict": [
                          "span"
                        ],
                        "description": "Doctype icon container shown next to the file name.",
                        "renderWhen": "propFilled",
                        "attributes": {
                          "static": {
                            "class": "slds-icon_container"
                          }
                        },
                        "children": [
                          {
                            "name": "titleIconSvg",
                            "restrict": [
                              "svg"
                            ],
                            "description": "SVG glyph for the title-bar doctype icon.",
                            "attributes": {
                              "static": {
                                "class": "slds-icon slds-icon_x-small"
                              }
                            }
                          },
                          {
                            "name": "titleIconAssistiveText",
                            "restrict": [
                              "span"
                            ],
                            "description": "Visually hidden label describing the doctype icon.",
                            "attributes": {
                              "static": {
                                "class": "slds-assistive-text"
                              }
                            }
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "name": "mediaBody",
                    "restrict": [
                      "div"
                    ],
                    "description": "Body slot of the media object containing the file name text.",
                    "attributes": {
                      "static": {
                        "class": "slds-media__body"
                      }
                    },
                    "children": [
                      {
                        "name": "text",
                        "restrict": [
                          "span"
                        ],
                        "description": "Truncating file name label.",
                        "attributes": {
                          "static": {
                            "class": "slds-file__text slds-truncate"
                          }
                        },
                        "children": [
                          {
                            "name": "textAssistiveText",
                            "restrict": [
                              "span"
                            ],
                            "description": "Visually hidden supplemental text for the file name (e.g., '+22 more files').",
                            "attributes": {
                              "static": {
                                "class": "slds-assistive-text"
                              }
                            }
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "name": "externalIcon",
        "restrict": [
          "div"
        ],
        "description": "External-source icon pinned to the top inline-start corner of the file card.",
        "attributes": {
          "static": {
            "class": "slds-file__external-icon"
          }
        },
        "children": [
          {
            "name": "externalIconContainer",
            "restrict": [
              "span"
            ],
            "description": "Icon container for the external-source glyph.",
            "attributes": {
              "static": {
                "class": "slds-file__icon slds-icon_container"
              }
            },
            "children": [
              {
                "name": "externalIconSvg",
                "restrict": [
                  "svg"
                ],
                "description": "SVG glyph for the external-source icon.",
                "attributes": {
                  "static": {
                    "class": "slds-icon slds-icon-text-default"
                  }
                }
              },
              {
                "name": "externalIconAssistiveText",
                "restrict": [
                  "span"
                ],
                "description": "Visually hidden label describing the external source.",
                "attributes": {
                  "static": {
                    "class": "slds-assistive-text"
                  }
                }
              }
            ]
          }
        ]
      },
      {
        "name": "actionsMenu",
        "restrict": [
          "div"
        ],
        "description": "Action menu pinned to the bottom inline-end corner of the file (typically download and overflow buttons).",
        "attributes": {
          "static": {
            "class": "slds-file__actions-menu"
          }
        },
        "children": [
          {
            "name": "buttonGroup",
            "restrict": [
              "div"
            ],
            "description": "Button group that hosts the action buttons.",
            "attributes": {
              "static": {
                "class": "slds-button-group"
              }
            },
            "children": [
              {
                "name": "actionButton",
                "restrict": [
                  "button"
                ],
                "description": "Icon button inside the actions menu (e.g., download, more actions).",
                "repeats": true,
                "attributes": {
                  "static": {
                    "class": "slds-button slds-button_icon slds-button_icon-x-small"
                  }
                },
                "children": [
                  {
                    "name": "actionButtonIcon",
                    "description": "SVG glyph inside the action button.",
                    "attributes": {
                      "static": {
                        "class": "slds-button__icon"
                      }
                    },
                    "component": "PrimitiveIcon"
                  },
                  {
                    "name": "actionButtonAssistiveText",
                    "restrict": [
                      "span"
                    ],
                    "description": "Visually hidden label describing the action button.",
                    "attributes": {
                      "static": {
                        "class": "slds-assistive-text"
                      }
                    }
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "name": "loadingIcon",
        "restrict": [
          "svg"
        ],
        "description": "Standalone loading-state icon variant used as a placeholder fill color.",
        "attributes": {
          "static": {
            "class": "slds-file__loading-icon"
          }
        }
      }
    ]
  },
  "componentRefs": {
    "PrimitiveIcon": {
      "description": "Bare SVG icon composed directly inside the component. The host node supplies the SVG class (e.g. slds-button__icon, slds-menu__item-icon) via componentProps; PrimitiveIcon contributes the sprite-href binding.",
      "props": {
        "iconName": {
          "type": "string",
          "required": true,
          "description": "Sprite reference for the icon glyph"
        }
      }
    }
  }
}