PhpSpreadsheet set background color of cell to white

PhpSpreadsheet set background color of cell to white

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

The Invisible White Background in PhpSpreadsheet

When working with PhpOffice\PhpSpreadsheet, setting a cell's background color can sometimes yield counterintuitive results. A common scenario involves attempting to clear a colored background or force a cell to appear white, only to find the result rendered as black or retaining the previous fill. This happens because Excel treats a lack of specific formatting commands differently from an explicit command to paint with white.

Consider the following code snippet where a developer attempts to set a solid fill of #FFFFFF:

$cells = 'A1';
$spreadsheet
    ->getActiveSheet()
    ->getStyle($cells)
    ->getFill()
    ->setFillType(\PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID)
    ->getStartColor(' #FFFFFF') // Note the leading space here
    ->setARGB('#FFFFFF');

In this specific example, the resulting cell background appears black rather than white. The root cause often lies not in the setARGB method itself, but in how the StartColor object is constructed and how PhpSpreadsheet handles default colors versus explicit overrides. When using the fluent interface to chain these calls, it is critical to ensure that the color constructor receives a valid string representation without accidental whitespace or type mismatches.

The discrepancy between the source material's code and the desired output highlights a subtle behavior in the library: if the StartColor object is instantiated with an empty string or a malformed value, PhpSpreadsheet may revert to a default fill that behaves unexpectedly when combined with other style properties, such as borders or fonts. In many versions of the library, simply calling getStartColor() and then setARGB() without passing a color hint initially can be problematic if the internal state expects a specific format.

To reliably force a white background, you must ensure that the fill type is explicitly set to FILL_SOLID and that the color is passed directly to the setter method as a raw string or hex value. The most robust approach avoids relying on the default constructor's inference capabilities when dealing with pure white, which can sometimes be confused with "no fill" depending on the Excel version and rendering engine.

Here is a corrected implementation pattern that ensures the background is explicitly painted white:

$cells = 'A1';
$spreadsheet
    ->getActiveSheet()
    ->getStyle($cells)
    ->getFill()
    ->setFillType(\PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID);

// Explicitly set the color using the setter without relying on constructor inference
$fill = $spreadsheet->getActiveSheet()->getStyle($cells)->getFill();
$fill->getStartColor()->setARGB('FF', 'FF', 'FF'); // Using RGB components for clarity
// OR strictly using Hex if preferred and ensuring no whitespace:
// $fill->getStartColor()->setARGB('#FFFFFF'); 

While setARGB() accepts hex strings, passing the Red, Green, and Blue components directly (e.g., 255 for each) eliminates ambiguity regarding string formatting or leading spaces. This method guarantees that the alpha channel is fully opaque and the color values are exactly 255, preventing any rendering engine from interpreting the fill as transparent or defaulting to a dark theme.

It is also worth noting that PhpSpreadsheet relies on the underlying OpenXML structure. If you are exporting to an XLSX file, the library generates XML files where the srgbColor attribute must be present. If your previous code resulted in a black background, it might have inadvertently set a color with low brightness or failed to update the fill type correctly before setting the color. Always verify that setFillType(\PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID) is called immediately before or after manipulating the color properties to ensure the fill model updates in memory before serialization.

For projects using Laravel, if you are integrating PhpSpreadsheet via a service provider or facade, remember that the underlying logic remains identical. The library does not maintain state between requests unless you explicitly pass the $spreadsheet object into your controller actions. Ensure you instantiate a fresh PhpSpreadsheet object for each export operation to avoid style bleed-over from previous runs.

By strictly defining the fill type and using component-based color setting or clean hex strings without whitespace, you eliminate the ambiguity that causes the background to render as black instead of white.

Our network